GitHub Pull Request Workflow
Manage the full lifecycle of GitHub pull requests — create, review, approve, request changes, merge, and clean up — using the gh CLI.
When to Use
- User wants to create a pull request from the current branch
- User wants to review or approve a PR
- User wants to merge a PR after approval
- User wants to check PR status, checks, or reviews
- User wants to list open PRs or find a specific PR
How to Use
1. Create a pull request
powershell# Interactive (opens editor for body) gh pr create # Non-interactive with all fields gh pr create --title "feat: add user authentication" --body "## Summary - Add JWT-based auth - Add login/logout endpoints - Add middleware for protected routes ## Test plan - [ ] Login with valid credentials - [ ] Reject invalid credentials - [ ] Access protected route with token" --base main --draft
2. List open PRs
powershellgh pr list gh pr list --state all --limit 20 gh pr list --author "@me" gh pr list --label "ready for review"
3. View PR details and diff
powershell# View PR summary gh pr view 15 # View with comments gh pr view 15 --comments # Show diff gh pr diff 15
4. Check PR status and CI checks
powershellgh pr checks 15 gh pr status # shows PRs relevant to you (authored, assigned, review requested)
5. Review a PR (approve / request changes / comment)
powershell# Approve gh pr review 15 --approve --body "LGTM! Clean implementation." # Request changes gh pr review 15 --request-changes --body "Please add unit tests for the auth middleware." # Leave a general comment gh pr review 15 --comment --body "Looks mostly good — just one question inline."
6. Merge a PR
powershell# Squash merge (recommended for feature branches) gh pr merge 15 --squash --delete-branch # Merge commit (preserves all commits) gh pr merge 15 --merge # Rebase merge gh pr merge 15 --rebase --delete-branch
7. Checkout a PR locally
powershell# Checkout a PR branch for local testing gh pr checkout 15 # Return to main when done git checkout main
8. Edit a PR (title, body, labels, reviewers)
powershell# Mark draft as ready for review gh pr ready 15 # Add reviewer gh pr edit 15 --add-reviewer alice,bob # Add label gh pr edit 15 --add-label "ready for review"
9. Close a PR without merging
powershellgh pr close 15 --comment "Closing in favour of PR #16 which takes a different approach."
Examples
"Create a PR from my current branch to main" → Use step 1 — fill in title and body describing the changes and test plan.
"Show me what CI checks are failing on PR 15"
→ Use step 4: gh pr checks 15 to see check names, status, and links to logs.
"Approve PR 22 and merge it with squash"
→ Use step 5 to approve, then step 6 with --squash --delete-branch.
Cautions
- Always check CI status (
gh pr checks) before merging — do not merge PRs with failing required checks --delete-branchremoves the remote branch after merge — confirm this is desired- Squash merge rewrites history — use merge commit for PRs where individual commit history matters
- Merging from
gh pr mergerequires merge permissions — the user needs write access to the repo


