Ship PR

Ship a PR

The canonical way to move a finished change from a feature branch to the repo's default branch through a pull request — for any GitHub repo, without hardcoding one project's build commands or check names.

There are two gates between your branch and the default branch:

• Mechanical — the repo's required CI checks. GitHub already enforces these via branch protection; let them run.
• Inferential — a human-judgment review of the diff. CI catches what it knows how to check; this catches behaviour, design, test coverage, risk, and rollback. This gate is the reason the skill exists.

Auto-merge is intentionally not used. gh pr merge --auto merges the moment CI passes, which skips the review gate entirely — that defeats the purpose. The merge command is run from this session, after the diff has been reviewed.

When NOT to use

• Draft / WIP PRs the user wants opened but not merged → not this flow; if it's already been invoked, just gh pr create --draft and stop.
• Changes to .github/workflows/, branch protection, or repo settings → these usually need a human in the GitHub UI too; flag it.
• Cutting a release (tags like v1.2.3) → releases follow the repo's own release process, not this flow.

The flow

Step 1 — Confirm the branch is shippable

git status -sb                                # clean except the expected diff?
git rev-parse --abbrev-ref HEAD               # the current branch
git fetch origin --quiet                      # refresh the remote base ref
git remote set-head origin --auto >/dev/null  # fetch never creates origin/HEAD; this does
BASE=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')
BASE=${BASE:-main}                            # the repo's default branch
git log --oneline "origin/$BASE..HEAD"        # commits actually exist

$BASE is the repo's default branch — usually main, sometimes master or develop. Don't assume main; use what was detected. Comparisons run against the remote ref origin/$BASE (hence the git fetch), so they match what GitHub will diff the PR against even when the local base branch is missing or stale — common in worktrees and feature-only checkouts.

• The remote isn't GitHub (git remote get-url origin) → stop; this flow is gh-only, tell the user (a GitLab "MR" needs a different flow).
• On the base branch → stop, make a feature branch first.
• No commits ahead of origin/$BASE → stop, nothing to ship.
• A PR may already exist for this branch (gh pr view succeeds) → still push (Step 2) so the PR has the latest commits, then skip Step 3 and continue at Step 4.

Step 2 — Push

git push -u origin "$(git rev-parse --abbrev-ref HEAD)"

If the repo installs a pre-push hook (Husky, core.hooksPath, etc.) it runs here automatically — don't re-run the same lint/test suite by hand. If no hook is installed, that's the user's setup; CI is still the gate.

Step 3 — Open the PR

Check for a PR template first — using it keeps the PR consistent with the repo's conventions instead of inventing a different shape:

ls .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md \
   PULL_REQUEST_TEMPLATE.md pull_request_template.md \
   docs/PULL_REQUEST_TEMPLATE.md docs/pull_request_template.md \
   .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null

If a template exists, fill in its sections honestly — including any cross-repo / checklist items (e.g. "needs a docs update?"). Do not discard it by passing a wholly custom --body. gh pr create without --body tries to open an interactive editor, so fill the template offline and pass it back:

gh pr create --title "<conventional commit subject>" --body-file <filled-template-file>

If there's no template, fall back to a sensible default:

gh pr create --title "<conventional commit subject>" --body "$(cat <<'EOF'
## Summary

- <what changed and why>

## Test plan

- [ ] <how you verified>
EOF
)"

Title rules:

• Conventional Commits prefix: feat: / fix: / docs: / refactor: / test: / chore: / ci: / perf: / style: / build: / revert:.
• Optional scope: fix(api):, feat(editor):.
• Keep under ~70 chars. Detail goes in the body.
• Several commits on the branch → write a fresh subject that sums up the whole PR (squash merge makes it the final commit subject).

Step 4 — Wait for CI

gh pr checks --watch

This blocks until every check finishes. (Run straight after gh pr create it can error with "no checks reported" before the first check registers — wait a few seconds and re-run; exit code 8 just means checks are still pending.) If a required check fails:

• Stop. Do not proceed to review or merge.
• Read the failure (gh run view --log-failed), explain it to the user, and ask whether to fix it now.
• Checks that aren't required (drift sensors, optional coverage, advisory scans) are informational — flag them, but they don't block the merge.

If you can't tell which checks are required, the ones branch protection enforces are; gh pr checks marks the rest, and the merge in Step 7 will refuse anyway if a required one is red.

Step 5 — Get a review

Once CI is green, the diff needs an inferential review — behaviour, design, test coverage, risk, rollback. Prefer to have the @claude GitHub bot do this first pass on the PR itself, so the review lives next to the code where the whole team can see it. Fall back to a local review only when the bot isn't available.

5a — Is the Claude bot wired up for this repo?

The bot is the Claude GitHub App driven by anthropics/claude-code-action. The reliable, permission-free signal is a workflow that uses it:

grep -rilE 'anthropics/claude-code-action|@claude' .github/workflows 2>/dev/null

(With repo-admin scope you could also confirm via gh api "repos/{owner}/{repo}/installations" --jq '.[].app.slug', but that 403s without admin — don't depend on it.)

• Match found → the bot can review; go to 5b.
• No match → the app isn't set up here; skip to 5d (local fallback).

5b — Request the review (or pick up an automated one)

PR=$(gh pr view --json number -q .number)

Some repos run claude-code-action automatically on every push (on: pull_request), so a claude[bot] review for the current commit may already be on its way — check before posting, to avoid asking twice:

gh pr view "$PR" --json comments \
  -q '.comments[] | select(.author.login|test("claude|github-actions")) | "\(.author.login)\t\(.createdAt)"'

(Comment objects carry createdAt, not updatedAt — and the sticky comment is edited in place, so an old timestamp can still be a live review. When in doubt, just mention the bot again.)

If there's no current bot comment, summon it with a mention. A focused prompt gets a more useful review than a bare "review this":

gh pr comment "$PR" --body "@claude please review this PR — focus on correctness, design, test coverage for the branches it adds, risk, and how it rolls back."

(@claude is the default trigger; a repo can rename it via trigger_phrase in its workflow. If the mention gets no response at all, check the workflow for a custom phrase.)

5c — Wait for the bot, then read its review

The bot answers in a single sticky comment it edits in place — it shows progress first (checkboxes like "Analyzing…") and fills in the real review when done. Wait for it to finish; don't act on a half-written comment. It usually lands in under a minute, occasionally a few minutes under load.

for i in $(seq 1 30); do
  body=$(gh pr view "$PR" --json comments \
    -q '[.comments[] | select(.author.login|test("claude|github-actions"))] | last | .body')
  if [ -n "$body" ] && ! printf '%s' "$body" | grep -qiE 'analyzing|in progress|- \[ \]'; then
    printf '%s\n' "$body" && break
  fi
  sleep 10
done

Re-fetch until the body reads as a completed review (no lingering "Analyzing…/in progress" markers). The author is normally claude[bot]; a repo using a custom github_token surfaces it as github-actions[bot] instead — either way it's obviously a Claude review by its content. A workflow configured to submit a formal PR review rather than a comment shows up under gh pr view --json reviews — glance there before declaring the bot unavailable. If nothing substantive shows up after a few minutes, treat the bot as unavailable and fall back. (If the loop times out but a bot comment is visible — e.g. a finished review whose body happens to contain unchecked checkboxes — read it manually instead of discarding it.) Carry whatever it found into Step 6.

5d — Local fallback

When the bot isn't wired up, or never returns a finished review, review the full PR diff yourself so the gate still closes:

git diff "origin/$BASE"...HEAD

• If a /code-review command or a repo-specific review skill is available, run it on the full diff — it's purpose-built for this.
• Otherwise review inline: behaviour, design, test coverage for the branches this PR adds, risk, and how it rolls back.

Either way, the findings feed into Step 6.