GitHub CLI

Overview

GitHub operations should be fast, scriptable, and verifiable. Stay in terminal flow—use web UI only for complex reviews.

MANDATORY: Always verify gh operations succeeded. Never assume commands worked.

Iron Law

•NO PR CREATION WITHOUT REVIEWING ALL COMMITS IN BRANCH
•NO PR MERGING WITHOUT USER CONFIRMATION
•NO FORCE OPERATIONS WITHOUT EXPLICIT REQUEST
•ALWAYS VERIFY GH OPERATIONS SUCCEEDED

When to Use / Not Use

Use gh CLI for: Creating PRs, monitoring CI, managing issues, checking out PRs for review, routine operations.

Use web UI for: Complex PR reviews, large diffs, repository settings, visual context.

Workflow 1: Creating a Pull Request

1. Gather Context (parallel)

bash

git status
git diff main...HEAD
git log main..HEAD --oneline

2. Analyze

•Understand every change in diff
•No "wip" or "debug" commits
•Branch has clear purpose
•Tests exist for new functionality

3. Create PR

bash

git push -u origin HEAD

gh pr create --title "feat: add auth middleware" --body "$(cat <<'EOF'
## Summary
- Implements JWT authentication middleware
- Adds login/logout endpoints

## Test plan
- [x] Unit tests pass
- [x] Integration tests cover auth flow

Fixes #142
EOF
)"

4. Verify

bash

gh pr view      # Confirm PR created
gh pr checks    # Verify CI started

Workflow 2: Monitor CI

bash

gh run list --limit 5     # Recent runs
gh run view               # Latest run details
gh run view --log-failed  # Failed job logs
gh run watch              # Real-time monitoring

Workflow 3: Issue Management

bash

gh issue list --assignee @me
gh issue view 123
gh issue create --title "bug: login fails" --body "..."
gh issue comment 123 --body "Fixed in PR #456"

Workflow 4: Review PR Locally

bash

gh pr list
gh pr view 456
gh pr checkout 456
git log main..HEAD
git diff main...HEAD
# Test locally
gh pr review --approve
# or
gh pr review --request-changes --body "Needs unit tests"

Workflow 5: Check PR Status

bash

gh pr status              # Your PR dashboard
gh pr view 123            # Full details
gh pr checks              # CI status
gh pr view 123 --json mergeable,mergeStateStatus

Safety Protocols

Never do without explicit user request:

•gh pr merge - Always confirm first
•gh pr close / gh issue close
•gh pr merge --admin - Bypasses checks
•Operations on repos you don't own

Always verify before operations:

•gh auth status - Check authentication
•gh repo view - Confirm correct repo
•gh pr checks - CI must pass before merge

Quick Reference

bash

# Pull Requests
gh pr create --fill                    # From commit messages
gh pr create --title "..." --body "..."
gh pr list
gh pr view 123
gh pr view --web
gh pr checkout 123
gh pr checks
gh pr review --approve
gh pr review --request-changes --body "..."
gh pr merge --squash
gh pr status

# Workflow Runs
gh run list --limit 10
gh run watch
gh run view
gh run view --log-failed

# Issues
gh issue list
gh issue list --assignee @me
gh issue view 456
gh issue create --title "..." --body "..."
gh issue comment 123 --body "..."

# Repository
gh repo view
gh repo view --web

# Auth
gh auth status
gh auth login

PR Body Template

markdown

## Summary
- [Main change and why]
- [Secondary change]

## Test plan
- [ ] Unit tests pass
- [ ] Integration tests cover new behavior

Fixes #[issue]

Key Takeaways

•Review all branch changes before PR - Not just latest commit
•Verify CI before merge - gh pr checks must show green
•Descriptive PR titles and bodies - High-level summary, not commit list
•Terminal for routine, web for complex - Know when to switch
•Confirm destructive operations - Merge, close, delete need user confirmation
•Link issues to PRs - "Fixes #123" auto-closes on merge