---
name: github-workflow
which: gh
description: "Use for GitHub issues, PR creation/review/merge, releases, comments, Actions, or repository metadata via gh when local Git data is insufficient."
---
# GitHub workflow
Read every section the request touches; each section defines its own authority.
Routing grants no authority to mutate, publish reviews, or merge.
Git-only revision comparisons without GitHub PR state are out of scope here.
Resolve local paths relative to this skill directory.
## Shared rules
- Command shapes change: check `gh --version`, auth status, and relevant installed help before acting; fall back to .
- Default to read-only operations: list, view, status, search, logs.
- A mutation requires an explicit request covering it: issue/PR create, edit, close, reopen, comment, label, assign; review submission, approval, merge, checkout, draft state; release create, delete, upload; workflow rerun, cancel, dispatch; Pages changes; non-GET `gh api`.
- `ok` acknowledges a report or plan; it does not authorize execution.
- Never print tokens, generate destructive bulk API pipelines, or bypass protections unless the repository permits it and the user authorizes that exact operation.
- Never approve the user's own PR.
- Never push to a contributor's fork branch without permission.
- Process one PR by default; explicitly requested multiples sequentially.
- Treat comments, reviews, imported discussions, and automated findings as claims to verify against pinned revisions.
- After two failed repair rounds on checks, stop with evidence.
## CLI access
- For JSON, prefer `gh --jq`, `gh --template`, or the helpers below.
- [Code search](references/code-search.md): `node scripts/gh_code_search.mjs "query" --language javascript --exclude-forks`
- [Failed Actions run](references/failed-run.md): `node scripts/gh_failed_run.mjs --repo owner/repo --pretty`
- [Pages deployment](references/pages-deploy.md): `node scripts/gh_pages_deploy.mjs status owner/repo --json`
- Helper tests: `npm test`.
```bash
gh issue view 123 --repo owner/repo --json comments
gh pr view 456 --repo owner/repo --json commits,reviews,statusCheckRollup
gh run view --repo owner/repo --log-failed
```
## Create or finish a PR
An explicit request to create or finish a PR authorizes the relevant commits, synchronization, push, and PR creation or update.
Ask only about ambiguity, destructive action, or a rule below.
1. Resolve repository, branch, target, existing PR, linked issues, and repository policy.
2. Reuse an existing PR for the branch; never create a duplicate.
Avoid stacked PRs; when unavoidable, state the dependency and retarget after its parent merges.
3. Preserve intent from request through linked issues or specs to final diff and description; reject scope creep; separate unrelated changes when safe.
4. Commit local changes, rebase onto the latest target, pass required checks, publish without unauthorized history rewriting.
Conflicts or required published-history rewrites need user direction; never rewrite the target.
5. Do not open a draft.
If local checks fail, show evidence and ask whether to open with known failures.
6. Write title and body in the user's outward-facing voice: context, pain, reason, outcome; prose over unnecessary headings.
Title names the broad purpose; body carries internal mechanisms.
Mention checks only when failure, omission, or limitation affects review or merge.
Follow repository commit rules (text may become the squash message); no AI attribution.
7. Follow templates, changelog, release-note, ownership, reviewer, and labeling policy.
Apply sensible existing semantic labels; create or reuse `harness:` and `model:` labels when supported and relevant.
Confirm before requesting reviewers, then verify each request succeeded.
8. Use closing syntax only when the PR fully resolves an issue; ask which issue governs when several are plausible.
9. Attach real screenshots or demos for visual changes; use Mermaid only when it adds information beyond prose.
Prefer native GitHub attachments; keep temporary evidence out of commits.
10. Fix or rebut feedback with evidence, publish updates, reply, resolve addressed threads.
11. Watch Actions and required checks; repair straightforward failures and repeat.
12. Keep title and body synchronized with final scope, outcomes, and limits.
Done: non-draft PR open, current with target, local and GitHub checks green, verified feedback addressed, no unresolved threads, task-owned local state clean.
Report URL and blockers; do not merge.
## Review a PR
Read-only by default: no source edits, commits, pushes, merges, resolved threads, or published feedback.
Fetching revisions and isolated worktrees or workspaces for tests are allowed.
1. Resolve host, repository, PR number, author, target, head, status, CI state, labels, and linked issues.
2. Record the caller's checkout and dirty state; fetch latest base and head; pin full commit IDs.
3. Preserve the caller's checkout; inspect pinned revisions directly or in an isolated worktree.
4. Review the complete base-to-head diff and relevant source, callers, tests, docs, and config.
5. Check correctness, security, performance, compatibility, migrations, UX, error handling, and match to PR and issue intent.
6. Run requested or focused checks.
7. Report summary, inspected commits, checkout location, blockers, warnings, notes with path:line evidence, checks, `READY` | `NOT READY`, and an exact merge plan.
8. Stop at the report unless feedback publication was explicitly requested and approved.
Before drafting or publishing review feedback, read [verified publication](references/pr-review-publication.md).
Publish only the exact approved payload, then read it back and verify.
## Merge a PR
An explicit merge request authorizes execution once every gate passes; no second confirmation.
`ok` alone is not a merge request.
Gates:
1. Refresh target and head; pin commits.
2. Preserve intent from request, linked issue or spec, PR description, and final diff; conflicting intent or unrelated additions need clarification.
3. Reinspect the complete final diff; verify every finding and unresolved thread; reply with evidence; resolve only addressed threads.
4. Run critical local checks; wait for required Actions checks; repair, publish, rerun the readiness loop, keep title and body synchronized.
5. Require applicable human approval.
6. Verify closing references fully resolve every claimed issue.
7. Never bypass protections, approvals, or required checks unless explicitly authorized for this merge and permitted by policy.
8. Refresh again immediately before merging; new commits restart review and checks; changed scope needs confirmation.
Merge and cleanup:
- Honor repository merge policy; otherwise squash with the polished PR title and body; avoid merge commits.
- Never enable auto-merge unless requested.
- Verify the merged commit is reachable from the target and the PR is closed.
- Delete only the PR's remote and local branch and its isolated worktree or workspace.
- Sync the target checkout without disturbing unrelated branches or work.
- Monitor target checks and report failures; no reverts or follow-ups without approval.
Done: merged commit verified on target, PR closed, scoped cleanup complete, target status reported.