repo-github-gh-cli

# GitHub CLI (SoloDevBoard) Use this skill when the user asks for command-line GitHub operations. Prioritise issue and project-management workflows used by SoloDevBoard. ## Tool Selection - Prefer GitHub MCP tools for issue search, pull requests, labels, and notifications when those tools cover the requested operation. - Prefer `gh` for GitHub Projects v2 item operations, field edits, and ad-hoc project inspection because those workflows are not fully covered by MCP in this repository. - Do not fall back to `gh` after an MCP failure unless the missing capability or limitation is clear. - Before mutating project items, confirm authentication state with `gh auth status` and ensure the token includes the `project` scope. ## Shell Selection - Default to bash examples for this repository when the current shell is WSL or Linux. - Do not use PowerShell backtick escaping or `Get-Date` syntax in WSL bash sessions. - Use cross-platform commands where possible. For example, prefer `gh project view 8 --owner markheydon --web` over shell-specific browser launch commands. ## Scope - Issue creation, updates, and triage - Label taxonomy operations aligned to `plan/LABEL_STRATEGY.md` - Pull request status and checks (creation metadata: [`plan/PULL_REQUEST_POLICY.md`](../../plan/PULL_REQUEST_POLICY.md)) - CI/CD workflow triggering and monitoring - Basic project board item operations Avoid broad, low-value commands (for example gists, codespaces, SSH/GPG key management) unless explicitly requested. ## Usage ### Label Taxonomy Always align labels to `plan/LABEL_STRATEGY.md` groups: - `type/` - `priority/` - `status/` - `area/` - `size/` Always apply at least one `type/` and one `priority/` label on issue creation. ### Vetted Command Patterns ```bash # Create an issue with repo taxonomy labels gh issue create \ --repo owner/repo \ --title "[Story] Add OAuth login" \ --body-file issue.md \ --label "type/story,priority/high,status/todo,area/infrastructure" # List open todo issues for a work area gh issue list \ --repo owner/repo \ --state open \ --label "status/todo,area/dashboard" \ --limit 50 # Transition issue state labels gh issue edit 123 \ --repo owner/repo \ --remove-label "status/todo" \ --add-label "status/in-progress" # Inspect pull request checks gh pr checks 123 --repo owner/repo # Add a multi-line issue comment using a body file to preserve real line breaks gh issue comment 123 \ --repo owner/repo \ --body-file comment.md # Trigger and monitor workflow runs gh workflow run ci.yml --repo owner/repo --ref main gh run list --repo owner/repo --workflow ci.yml --limit 10 # Add an issue to a project (requires project permissions) gh project item-add 5 --owner owner --url https://github.com/owner/repo/issues/123 # === SoloDevBoard Roadmap (Project #8) === # List all project items and their current state gh project item-list 8 --owner markheydon --format json # Add an issue to the SoloDevBoard Roadmap gh project item-add 8 --owner markheydon --url https://github.com/markheydon/solo-dev-board/issues/123 # View the roadmap board in the browser gh project view 8 --owner markheydon --web # Set a single-select project field on an existing item gh project item-edit \ --id "$item_id" \ --project-id "PVT_kwHOAJefG84BQ6bh" \ --field-id "PVTSSF_lAHOAJefG84BQ6bhzg-5WGY" \ --single-select-option-id "df9275ed" # Set a number field on an existing item gh project item-edit \ --id "$item_id" \ --project-id "PVT_kwHOAJefG84BQ6bh" \ --field-id "PVTF_lAHOAJefG84BQ6bhzg_Lx34" \ --number 1 # NOTE: Prefer `gh project item-edit` for project field updates. # Use raw GraphQL only when `gh project` does not expose the required operation. # See `.agents/skills/repo-github-project/SKILL.md` for the SoloDevBoard-specific field IDs and queue workflow. # Capture the project item id from item-add (item-list defaults to 30 items). item_id=$(gh project item-add 8 --owner markheydon \ --url https://github.com/markheydon/solo-dev-board/issues/123 \ --format json --jq .id) # Look up an existing item without listing the whole board. gh project item-list 8 --owner markheydon --query 123 --format json --jq '.items[0].id' ``` ### Issue hierarchy and blocking `gh issue` has **no** first-class sub-issue or block commands yet ([cli/cli#11757](https://github.com/cli/cli/issues/11757), [cli/cli#10298](https://github.com/cli/cli/issues/10298)). Agents must still set both via API and must **not** leave them as a GitHub UI chore for the user. **Sub-issues:** GitHub MCP `sub_issue_write` (`method: add`). `sub_issue_id` is the issue **database id** (`gh api repos/OWNER/REPO/issues/N --jq .id`), not the `#` number. **Blocking:** REST [issue dependencies](https://docs.github.com/en/rest/issues/issue-dependencies). POST against the **blocked** issue; `issue_id` is the **blocking** issue's database id as a JSON integer (a quoted string returns 422). ```bash # Resolve database ids (not issue numbers). blocker_id=$(gh api repos/markheydon/solo-dev-board/issues/382 --jq .id) # Mark #273 as blocked by #382. gh api -X POST repos/markheydon/solo-dev-board/issues/273/dependencies/blocked_by \ --input - <<EOF {"issue_id": ${blocker_id}} EOF # HTTP 422 "already been taken" means the link already exists — treat as success. # List current blockers: gh api repos/markheydon/solo-dev-board/issues/273/dependencies/blocked_by --jq '.[].number' ``` The inverse endpoint is `.../issues/{number}/dependencies/blocking` (this issue blocks others). Prefer `blocked_by` so the dependent issue is the path parameter. ### Safety Rules - Use `--repo owner/repo` for multi-repository operations to avoid acting on the wrong repository. - Prefer `gh issue edit`/`gh pr edit` over ad-hoc API mutations for common updates. - Prefer `gh project item-edit` over raw `gh api graphql` mutations for project field updates. - For multi-line issue or pull request comments, prefer `--body-file` or a heredoc-backed temp file instead of embedding `\n` escapes in `--body` strings. - For bulk operations, list and review targets first before piping into mutation commands. - Confirm authentication state with `gh auth status` before mutating operations. - In WSL or Linux, keep jq filters in single quotes and avoid PowerShell-specific quoting patterns. Refer to the [GitHub CLI documentation](https://cli.github.com/manual/) for command details.