| name | github-pr-workflow |
| description | Pull request lifecycle: create, review, merge, manage (gh CLI) |
| category | developer |
| version | 1.0.0 |
| origin | aiden |
| license | Apache-2.0 |
| tags | github, pull-request, pr, review, merge, gh-cli, code-review, workflow, branch, diff |
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
# 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
gh 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
# 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
gh pr checks 15
gh pr status # shows PRs relevant to you (authored, assigned, review requested)
5. Review a PR (approve / request changes / comment)
# 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
# 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
# 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)
# 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
gh 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-branch removes 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 merge requires merge permissions — the user needs write access to the repo
