GitHub PR Workflow
Use this skill for the end-to-end pull request loop from branch creation through merge readiness.
Default Sequence
- Verify GitHub CLI authentication if the workflow will use
gh. - Sync the base branch.
- Create a focused branch for one change.
- Implement and validate locally.
- Review the complete content being committed for credentials, then commit with a clear message.
- Review every outgoing commit for credentials, then push and open or update the PR.
- Check CI and fix failures.
- Address review feedback.
- Merge only when the branch is green and approved.
Publication Safety
Inspect the actual files being committed, including unchanged content in those files. Before pushing, establish the destination and complete outgoing commit range from current Git state, then review all files and intermediate commits that will become reachable there. A diff summary or a clean final tree can miss a secret retained in an earlier commit. Use an available credential scanner with matching values suppressed, and inspect relevant content through permitted tools; never paste secret values into a reply, commit message, PR, or diagnostic.
If a suspected secret is present, stop before publication and report its file and line or commit without the value. Removing it from the latest file does not remove it from history. Ask the user to resolve credentials and authorize any history rewrite; do not delete their changes or rewrite history on your own. If the outgoing range or its contents cannot be verified, explain that blocker.
Use the configured Git identity and approved authentication. A failed commit or push does not authorize a fabricated author, a remote/protocol change, or a search of credential stores. Read-only status checks are fine; explain the missing prerequisite when the approved path is unavailable.
Core Commands
Verify GitHub CLI Auth
gh auth status
Run this before any git or PR workflow steps that depend on gh. If it fails,
fix authentication first so the workflow does not stop later during gh pr create,
gh pr checks, or other PR commands.
Prepare the Branch
git fetch origin
git checkout main
git pull --ff-only origin main
git checkout -b feat/short-description
Use the repository's actual base branch if it is not main.
Commit Clearly
git status --short
git add path/to/file.ts tests/path/to/file.test.ts
git commit -m "feat: short summary"
Keep commits scoped and explain user-visible intent in the subject line.
Push and Open the PR
git push -u origin HEAD
gh pr create --fill
When --fill is not enough, make the body explicit with:
- summary
- test plan
- risks or rollout notes
- linked issue or ticket
Useful variants:
gh pr create --draft
gh pr create --base main --title "feat: short summary" --body-file /tmp/pr-body.md
gh pr view --web
If gh is unavailable, complete the local git steps and use the GitHub UI for
PR-specific actions.
CI and Merge Readiness
Check status after every push:
gh pr checks
gh pr checks --watch
gh run list --branch "$(git branch --show-current)" --limit 5
gh run view <run-id> --log-failed
When a check fails:
- inspect the failing job or logs
- reproduce locally if possible
- fix the smallest confirmed problem
- rerun targeted validation
- push again and re-check CI
Do not merge red CI unless the user explicitly accepts that risk.
Review Feedback Loop
Use the PR conversation as the source of truth:
gh pr view 123 --comments
gh pr comment 123 --body "Addressed the failing migration path."
gh pr review 123 --comment --body "Applied the requested cleanup."
When feedback arrives:
- group related comments into one fix pass when practical
- mention what changed, not just that it is done
- rerun the checks most likely to regress
- keep follow-up commits small and labeled by intent
Merge Options
Use the repository's preferred merge style:
gh pr merge 123 --squash
gh pr merge 123 --merge
gh pr merge 123 --rebase
Before merging, verify:
- CI is green
- required reviewers approved
- the PR description still matches the implementation
- no unresolved review threads remain if the repo treats them as blockers
Working Rules
- Prefer small PRs over broad mixed-scope branches.
- Keep the PR body current when scope changes.
- Do not hide risky follow-up work in "later" comments; put it in the PR body or linked issue.
- If a change needs multiple dependent PRs, make the stack explicit.
- When CI is noisy or flaky, call that out instead of pretending the branch is stable.
