github-cli

name	github-cli
description	Apply when using the gh CLI to manage pull requests, issues, releases, or CI workflows on GitHub.
license	MIT
version	1.0.0
tokens_target	1200
triggers	["gh cli","github pr create","github issues"]
loads_after	["git-conventions"]
supersedes	[]

Sub-Skill: GitHub CLI (gh) Conventions

Purpose: Consistent, auditable use of the gh CLI for PRs, issues, releases, and CI — preventing gate bypasses and silent failures.

---

Rules

Authentication & Scopes

1. Check auth scope before scripting. Before running gh in CI or scripts, always verify the required scopes are granted with gh auth status; missing scopes produce silent 404s rather than auth errors.
2. Use token env var in CI. Always pass GH_TOKEN (or GITHUB_TOKEN) via environment variable in CI pipelines; never hard-code tokens or use gh auth login --with-token interactively in automated contexts.

Pull Requests

3. Include all required labels on PR creation. Always pass --label for every gate-required label when running gh pr create; omitting a label silently bypasses automated approval gates. Reference: ERR-2026-023
4. Set reviewer on creation. Always use --reviewer <handle> when creating PRs that require CODEOWNERS approval; adding reviewers after creation delays the review clock.
5. Open as draft when work is incomplete. Use gh pr create --draft for PRs not yet ready for review; never open a ready-for-review PR on a branch with failing CI.
6. Link issues explicitly. Always include --body "Closes #<issue>" or --body "Fixes #<issue>" so GitHub auto-closes the linked issue on merge; never rely on branch name alone for issue linkage.

Issues

7. Assign and label on creation. Use gh issue create --assignee @me --label <label> rather than creating bare issues and editing them in a second step; unassigned, unlabelled issues fall out of triage queues.
8. Use JSON output for scripting. Prefer gh issue list --json number,title,labels over parsing human-readable output; the --json flag is stable across gh versions, plain text is not.

CI / Workflows

9. Trigger runs explicitly when needed. Use gh workflow run <workflow.yml> --ref <branch> to trigger a workflow rather than pushing an empty commit; empty commits pollute history.
10. Watch run status in scripts. After triggering a workflow, use gh run watch <run-id> or poll gh run view <run-id> --json conclusion rather than sleeping for a fixed duration.

Releases & API

11. Create releases from tags, not branches. Always run gh release create <tag> --generate-notes after pushing the tag; never target a branch directly, as branch-based releases produce non-reproducible artifacts.
12. Use gh api for endpoints not covered by subcommands. Prefer gh api repos/{owner}/{repo}/pulls --jq '.[].number' over raw curl with manual auth headers; gh api inherits the active auth context automatically.
13. Define aliases for repeated commands. Use gh alias set to capture long flag combinations used more than twice in a project; aliases are stored in ~/.config/gh/config.yml and are portable across machines via dotfiles.

---

See also

• skills/git-conventions/SKILL.md
• skills/error-log/SKILL.md