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

1. 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
2. Set reviewer on creation. Always use --reviewer <handle> when creating PRs that require CODEOWNERS approval; adding reviewers after creation delays the review clock.
3. 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.
4. 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

1. 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.
2. 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

1. 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.
2. 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

1. 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.
2. 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.
3. 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