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

If gh is not installed, run the setup script:

uv run .claude/skills/gh/scripts/setup_gh.py

The script:

1. Checks if gh is already installed via shutil.which
2. Detects platform (Linux, macOS, Windows) and architecture
3. Fetches the latest release from https://github.com/cli/cli/releases/latest
4. Downloads the correct archive with SHA256 verification from checksums file
5. Extracts and installs the binary to a writable PATH directory
6. Uses GITHUB_TOKEN for authenticated requests; falls back to anonymous if auth fails (401/403)

CLI options:

--force     Reinstall even if already at latest version
--dry-run   Show what would happen without installing
--bin-dir   Override install directory (default: auto-detect from PATH)

---

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 Jamie-BitFlight/claude_skills

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 Jamie-BitFlight/claude_skills

# View PR details
gh pr view <number> -R Jamie-BitFlight/claude_skills

# Check PR CI status
gh pr checks <number> -R Jamie-BitFlight/claude_skills

# Create PR
gh pr create -R Jamie-BitFlight/claude_skills --title "title" --body "body"

# View PR comments
gh api repos/Jamie-BitFlight/claude_skills/pulls/<number>/comments

Issues

# List issues
gh issue list -R Jamie-BitFlight/claude_skills

# List by label
gh issue list -R Jamie-BitFlight/claude_skills --label "priority:p1" --state open

# Create issue with labels and milestone
gh issue create -R Jamie-BitFlight/claude_skills \
  --title "feat: add feature X" \
  --label "priority:p1" --label "type:feature" \
  --milestone "v1.0"

# View issue
gh issue view <number> -R Jamie-BitFlight/claude_skills

# Close issue with comment
gh issue close <number> -R Jamie-BitFlight/claude_skills --comment "Implemented in PR #N"

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

Labels

# List all labels
gh label list -R Jamie-BitFlight/claude_skills

# Create label
gh label create "priority:p1" --color "E99695" \
  --description "High priority" -R Jamie-BitFlight/claude_skills

# Setup full label taxonomy (automation script)
uv run .claude/skills/gh/scripts/github_project_setup.py labels \
  --repo Jamie-BitFlight/claude_skills

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

Projects V2

# List projects
gh project list --owner Jamie-BitFlight

# Create project
gh project create --owner Jamie-BitFlight --title "claude_skills Backlog"

# Add issue to project
gh project item-add 1 --owner Jamie-BitFlight \
  --url https://github.com/Jamie-BitFlight/claude_skills/issues/42

# Full project setup (automation script)
uv run .claude/skills/gh/scripts/github_project_setup.py setup \
  --repo Jamie-BitFlight/claude_skills

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/Jamie-BitFlight/claude_skills/milestones

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

# Assign milestone to issue
gh api repos/Jamie-BitFlight/claude_skills/issues/42 \
  -X PATCH -F milestone=1

See milestones.md for full CRUD reference.

Workflow Runs

# List recent runs
gh run list -R Jamie-BitFlight/claude_skills --limit 5

# View specific run
gh run view <run-id> -R Jamie-BitFlight/claude_skills

# View failed job logs
gh run view <run-id> -R Jamie-BitFlight/claude_skills --log-failed

Releases

# List releases
gh release list -R Jamie-BitFlight/claude_skills

# View latest release
gh release view --repo <owner>/<repo>

API (Direct)

# GET request
gh api repos/<owner>/<repo>

# POST with fields
gh api repos/<owner>/<repo>/issues -f title="Bug" -f body="Details"

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

# Paginated results
gh api repos/<owner>/<repo>/contributors --paginate

Repository

# Clone
gh repo clone <owner>/<repo>

# View repo info
gh repo view -R <owner>/<repo>

</gh_commands>

---

Output Formatting

# JSON output
gh pr list -R Jamie-BitFlight/claude_skills --json number,title,state

# JQ filtering
gh pr list -R Jamie-BitFlight/claude_skills --json number,title --jq '.[].title'

# Template formatting
gh pr list -R Jamie-BitFlight/claude_skills --json number,title \
  --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}'

---

Automation — Python Script

For multi-step operations (label setup, milestone creation, project init, issue import), use:

# Full project setup
uv run .claude/skills/gh/scripts/github_project_setup.py setup

# Labels only
uv run .claude/skills/gh/scripts/github_project_setup.py labels

# Milestone management
uv run .claude/skills/gh/scripts/github_project_setup.py milestone list
uv run .claude/skills/gh/scripts/github_project_setup.py milestone create --title "v1.0" --due 2026-03-31

# Issue management
uv run .claude/skills/gh/scripts/github_project_setup.py issue list --priority p1
uv run .claude/skills/gh/scripts/github_project_setup.py issue create --title "feat: X" --priority-label priority:p1

The script delegates all GitHub operations to the authenticated gh CLI — no separate API tokens or Python HTTP clients needed.

---

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