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-branch

When to reach for this:

• Opening PRs without leaving the terminal
• Watching ruff/pytest workflow 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-branch

What this demonstrates:

• --fill uses commit messages for draft body when appropriate
• --watch blocks 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

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 - repo and workflow needed for private Actions. Fix: gh auth refresh -s repo,workflow.
• Wrong default repo - gh targets 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 --merge per ADR.

Alternatives

FAQs

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+.