GitHub CLI
The gh CLI manages pull requests, issues, Actions runs, and releases from the terminal - matching how Python teams already script uv and pytest in CI.
Recipe
gh auth login
gh pr create --fill --base main
gh pr checks --watch
gh pr merge --squash --delete-branchWhen to reach for this:
- Opening PRs without leaving the terminal
- Watching
ruff/pytestworkflow on a push - Bulk issue labeling or release asset upload
- Scripting repo hygiene in platform team runbooks
Working Example
# After feature work
git push -u origin feat/bill-42-tax
gh pr create \
--title "feat(billing): add tax line item [BILL-42]" \
--body "Adds VAT calculation; updates uv.lock for pydantic bump." \
--reviewer @acme/billing-team
# Watch CI (same steps as .github/workflows/pr.yml)
gh pr checks 42 --watch
# Request changes addressed - merge when green
gh pr merge 42 --squash --delete-branchWhat this demonstrates:
--filluses commit messages for draft body when appropriate--watchblocks until required checks complete- Squash merge policy aligned with branching doc
- Branch auto-delete keeps remote tidy
Deep Dive
How It Works
gh auth- Stores token or uses SSH for git operations.gh pr- Wraps GitHub Pull Requests REST/GraphQL.gh run- Lists and views Actions workflow runs.gh api- Raw authenticated API for custom scripts.
High-Value Commands
| Task | Command |
|---|---|
| Checkout PR locally | gh pr checkout 42 |
| View PR diff | gh pr diff 42 |
| Re-run failed job | gh run rerun <run-id> --failed |
| Create release | gh release create v1.2.0 dist/* |
| List issues | gh issue list --label bug |
Python Notes
# Comment pytest failure snippet on PR
gh pr comment 42 --body "$(uv run pytest -q 2>&1 | tail -20)"Gotchas
- Auth token scope -
repoandworkflowneeded for private Actions. Fix:gh auth refresh -s repo,workflow. - Wrong default repo -
ghtargets cwd remote. Fix:gh repo set-default acme/billing-api. - Merge before CI green - Bypasses policy if admin. Fix: wait for
gh pr checks. - PR template skipped - Empty bodies slow review. Fix:
.github/pull_request_template.md+gh pr create --template. - Leaking secrets in comments - Paste logs may include tokens. Fix: redact before
gh pr comment. - Squash vs merge mismatch - Org policy may forbid squash. Fix:
gh pr merge --mergeper ADR.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| GitHub web UI | Visual review of images/UI | Repetitive PR creation |
hub (legacy) | Old scripts | New automation - use gh |
GitLab glab | GitLab hosting | GitHub org |
| API + curl | Exotic endpoints | gh api already wraps auth |
FAQs
SSH or HTTPS for gh auth?
SSH if git already uses SSH keys; HTTPS with token for fine-grained PAT control.
gh in CI?
Use GH_TOKEN secret with least scope - not personal PAT on shared runners.
Draft PR from CLI?
gh pr create --draft for early feedback before review queue.
Approve PR as reviewer?
gh pr review 42 --approve when policy allows CLI reviews.
Trigger workflow_dispatch?
gh workflow run pr.yml --ref feat/branch
Download Actions artifacts?
gh run download <run-id> -n coverage-report
Multiple remotes?
gh pr create --repo acme/other-service targets explicit repo.
Issue from failed CI?
gh issue create --title "CI flaky test_tax" --body "run id ..."
Alias common flows?
gh alias set prc 'pr create --fill --web' - team shares aliases doc.
Enterprise Server?
gh auth login --hostname github.acme.com for GHES.
Related
- Essential Git Commands - git push before PR
- CI/CD Pipelines - workflow parity
- Branching & Merging - merge policies
- Git Best Practices - team git norms
Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.