Home Assistant Emby GitHub Operations

Overview

All work on this repository MUST be tracked via GitHub Issues and the Project Board.

This skill covers GitHub CLI operations, project board queries, issue lifecycle management, and the mandatory linking of all code changes to issues.

The Iron Law

NO CODE CHANGES WITHOUT A LINKED GITHUB ISSUE

This is a VIOLATION. Every commit, every PR, every change must reference an issue.

Before writing ANY code:

1. Check if an issue exists for this work
2. If not, create one
3. Link all commits and PRs to the issue

Project Details

Label Reference

Type Labels

Priority Labels

Component Labels

Status Labels

Triage Labels

Special Labels

Common GitHub CLI Operations

Query Issues

# List all triaged bugs ready for investigation
gh issue list --label "bug" --label "ai-triaged" --state open -L 20

# List confirmed bugs ready for fixing
gh issue list --label "bug" --label "confirmed" --state open -L 20

# List high-priority items
gh issue list --label "priority: high" --state open -L 20

# List issues in progress
gh issue list --label "status: in-progress" --state open -L 20

# View specific issue with full details
gh issue view 42

# View issue comments
gh issue view 42 --comments

# Search for related issues
gh issue list --search "websocket connection" --state all

Update Issues

# Add labels
gh issue edit 42 --add-label "confirmed,priority: high"

# Remove labels
gh issue edit 42 --remove-label "needs-triage"

# Add comment
gh issue comment 42 --body "Investigation complete. See analysis below..."

# Assign to self
gh issue edit 42 --add-assignee @me

# Close issue
gh issue close 42 --reason completed

Project Board

# List project items
gh project item-list 3 --owner troykelly --format json

# Get project field IDs (for status updates)
gh project field-list 3 --owner troykelly

Create Issues

# Create bug issue
gh issue create \
  --title "Bug: Description" \
  --body "## Description\n\n## Steps to Reproduce\n\n## Expected Behavior\n\n## Actual Behavior" \
  --label "bug,needs-triage"

# Create feature issue
gh issue create \
  --title "Feature: Description" \
  --body "## Description\n\n## Use Case\n\n## Proposed Solution" \
  --label "enhancement,needs-triage"

Branch Naming Convention

issue-{number}-{short-description}

Examples:

• issue-42-fix-websocket-reconnect
• issue-123-add-playlist-service
• issue-7-media-player-volume-bug

Rules:

• Always include issue number
• Use lowercase
• Use hyphens, not underscores
• Keep description short (3-5 words)

Commit Message Format

type(scope): description (#issue)

Types:

Scopes:

Examples:

git commit -m "fix(websocket): handle reconnection on server restart (#42)"
git commit -m "feat(services): add playlist creation service (#123)"
git commit -m "test(media-player): add volume control edge cases (#7)"

Pull Request Format

gh pr create \
  --title "Fix: Websocket reconnection on server restart" \
  --body "$(cat <<'EOF'
## Summary

Brief description of changes.

Fixes #42

## Changes

- Change 1
- Change 2
- Change 3

## Test Plan

- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Edge cases verified

## Breaking Changes

None / List any breaking changes

---
🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

Critical: Always include Fixes #N or Closes #N in the PR body to auto-close the issue on merge.

Workflow Integration

Before Starting Work

# 1. Check for existing issue
gh issue list --search "your topic"

# 2. If none exists, create one
gh issue create --title "..." --body "..."

# 3. Assign to yourself
gh issue edit {N} --add-assignee @me

# 4. Update status
gh issue edit {N} --add-label "status: in-progress"

# 5. Create branch
git checkout -b issue-{N}-description

During Work

# Commit with issue reference
git commit -m "type(scope): message (#N)"

# Update issue with progress
gh issue comment {N} --body "Progress update: ..."

After Work Complete

# Create PR linked to issue
gh pr create --title "..." --body "Fixes #N ..."

# Wait for CI and review
gh pr checks

# After merge, issue auto-closes

Anti-Patterns

VIOLATION: Code Without Issue

# WRONG - No issue reference
git commit -m "fix websocket bug"

# CORRECT - Always reference issue
git commit -m "fix(websocket): handle disconnect (#42)"

VIOLATION: PR Without Issue Link

# WRONG - PR body missing issue link
gh pr create --body "Fixed the thing"

# CORRECT - Always link to issue
gh pr create --body "Fixes #42\n\nFixed the websocket disconnect issue"

VIOLATION: Working Without Checking Project

# WRONG - Start coding immediately
vim custom_components/embymedia/websocket.py

# CORRECT - Check project first
gh issue list --label "status: in-progress" --assignee @me
gh issue view 42
# Then start coding

The Bottom Line

Every code change links to an issue. No exceptions.

1. Issue exists before code
2. Branch named with issue number
3. Commits reference issue number
4. PR links to issue with Fixes #N
5. Issue auto-closes on merge