GitHub CLI (gh) — Setup and Usage

Purpose

Ensures the GitHub CLI (gh) is available and provides correct usage patterns for AI agents operating in environments where gh may not be pre-installed and where git remotes point to local proxies instead of github.com.

When to Use

• gh command not found or shutil.which("gh") returns None
• Need to interact with GitHub API (issues, PRs, releases, workflows)
• Repository remote does not point to github.com (proxy environments)
• Need authenticated GitHub operations with GITHUB_TOKEN
• Managing GitHub Issues, Projects V2, Milestones, or Labels

---

Installation

gh is assumed to be already installed via the system package manager:

• macOS: brew install gh
• Windows: winget install GitHub.cli
• Linux (Debian/Ubuntu): apt install gh

For CI monitoring operations (watching workflow runs, checking statuses, waiting for jobs), use ci_monitor.cjs:

node src/resources/skills/github-workflows/references/gh/scripts/ci_monitor.cjs

---

Authentication

GITHUB_TOKEN environment variable provides automatic authentication. No manual gh auth login needed.

# Verify authentication
gh auth status

If GITHUB_TOKEN is set, gh authenticates automatically for all API calls.

---

Repository Detection

<repo_detection>

Git remote points to a local proxy (127.0.0.1), NOT github.com. Every gh command fails without explicit repo specification:

failed to determine base repo: none of the git remotes configured for this
repository point to a known GitHub host.

RULE: Pass -R (or --repo) on EVERY gh command:

gh <command> -R gsd-build/gsd-2

This applies to ALL gh subcommands: pr, issue, run, api, release, project, etc.

</repo_detection>

---

Common Commands (v2.87.0)

<gh_commands>

Pull Requests

# List open PRs
gh pr list -R gsd-build/gsd-2

# View PR details
gh pr view <number> -R gsd-build/gsd-2

# Check PR CI status
gh pr checks <number> -R gsd-build/gsd-2

# Create PR
gh pr create -R gsd-build/gsd-2 --title "title" --body "body"

# View PR comments
gh api repos/gsd-build/gsd-2/pulls/<number>/comments

Issues

# List issues
gh issue list -R gsd-build/gsd-2

# List by label
gh issue list -R gsd-build/gsd-2 --label "priority:p1" --state open

# Create issue with labels and milestone
# NOTE: Do NOT use labels for issue classification (bug, feature, etc.)
# Use labels for metadata (priority, status, auto-generated) only.
# Issue classification uses GitHub Issue Types, set via GraphQL after creation.
gh issue create -R gsd-build/gsd-2 \
  --title "feat: add feature X" \
  --label "priority:p1" \
  --milestone "v1.0"

# View issue
gh issue view <number> -R gsd-build/gsd-2

# Close issue with comment
gh issue close <number> -R gsd-build/gsd-2 --comment "Implemented in PR #N"

# Edit labels on issue
gh issue edit <number> -R gsd-build/gsd-2 \
  --add-label "status:in-progress" \
  --remove-label "status:needs-grooming"

Issue Types (Classification)

gh issue create has no --type flag. Issue types (Bug, Feature Request, etc.) are set via GraphQL after creation:

# Step 1: Create the issue (returns URL)
ISSUE_URL=$(gh issue create -R gsd-build/gsd-2 \
  --title "..." --body "...")

# Step 2: Set the issue type via GraphQL
ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
ISSUE_ID=$(gh api graphql -f query='{ repository(owner:"gsd-build",name:"gsd-2") { issue(number:'"$ISSUE_NUM"') { id } } }' --jq '.data.repository.issue.id')
TYPE_ID=$(gh api graphql -f query='{ repository(owner:"gsd-build",name:"gsd-2") { issueTypes(first:20) { nodes { id name } } } }' --jq '.data.repository.issueTypes.nodes[] | select(.name=="Bug") | .id')
gh api graphql -f query='mutation { updateIssue(input:{id:"'"$ISSUE_ID"'",issueTypeId:"'"$TYPE_ID"'"}) { issue { number } } }'

Replace "Bug" with the appropriate type name ("Feature Request", "Task", etc.).

Labels

# List all labels
gh label list -R gsd-build/gsd-2

# Create label
gh label create "priority:p1" --color "E99695" \
  --description "High priority" -R gsd-build/gsd-2

See labels.md for the full taxonomy and color codes.

Projects V2

# List projects
gh project list --owner gsd-build

# Create project
gh project create --owner gsd-build --title "gsd-2 Backlog"

# Add issue to project
gh project item-add 1 --owner gsd-build \
  --url https://github.com/gsd-build/gsd-2/issues/42

See projects-v2.md for field creation and item editing commands.

Milestones

gh has no native milestone subcommand — use gh api with the REST endpoint:

# List milestones
gh api repos/gsd-build/gsd-2/milestones

# Create milestone
gh api repos/gsd-build/gsd-2/milestones \
  -X POST -f title="v1.0" -f due_on="2026-03-31T00:00:00Z"

# Assign milestone to issue
gh api repos/gsd-build/gsd-2/issues/42 \
  -X PATCH -F milestone=1

See milestones.md for full CRUD reference.

Workflow Runs

# List recent runs
gh run list -R gsd-build/gsd-2 --limit 5

# View specific run
gh run view <run-id> -R gsd-build/gsd-2

# View failed job logs
gh run view <run-id> -R gsd-build/gsd-2 --log-failed

Releases

# List releases
gh release list -R gsd-build/gsd-2

# View latest release
gh release view --repo gsd-build/gsd-2

API (Direct)

# GET request
gh api repos/gsd-build/gsd-2

# POST with fields
gh api repos/gsd-build/gsd-2/issues -f title="Bug" -f body="Details"

# GraphQL
gh api graphql -f query='{ viewer { login } }'

# Paginated results
gh api repos/gsd-build/gsd-2/contributors --paginate

Repository

# Clone
gh repo clone gsd-build/gsd-2

# View repo info
gh repo view -R gsd-build/gsd-2

</gh_commands>

---

Output Formatting

# JSON output
gh pr list -R gsd-build/gsd-2 --json number,title,state

# JQ filtering
gh pr list -R gsd-build/gsd-2 --json number,title --jq '.[].title'

# Template formatting
gh pr list -R gsd-build/gsd-2 --json number,title \
  --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'

---

Reference Files

• labels.md — Label taxonomy (priority, type, status), color codes, bulk setup
• milestones.md — Milestone CRUD via REST API, naming conventions
• projects-v2.md — GitHub Projects V2 commands, custom fields, GraphQL queries
• issue-stories.md — Issue as story format, body template, lifecycle, backlog item field mapping

---

Sources

• GitHub CLI Manual — official reference
• GitHub CLI Releases — binary downloads
• GitHub REST API — Issues — milestones, labels, issues
• GitHub Projects V2 API — GraphQL API
• gh version 2.87.2 (2026-02-20) — version verified by installation test