github-pr-workflow

# 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 ```powershell 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 ```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 ```powershell gh 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 ```powershell 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