From cccb2f0aa1e6f3e500776e7b715b9f34b666b0fb Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Mon, 6 Jul 2026 13:27:48 -0400 Subject: [PATCH 1/2] docs(agents): teach agents to merge via the Trunk merge queue Add a "Merging PRs" section to AGENTS.md and a merging-prs skill so Claude and Codex enqueue PRs with `/trunk merge` and babysit them through the queue (preflight, poll the "Trunk Merge Queue" check run, handle failures) instead of running `gh pr merge`, which the ruleset blocks. Generated-By: PostHog Code Task-Id: 2d321370-0c0e-4d63-89d7-e367ebd9ecee --- .claude/skills/merging-prs/SKILL.md | 105 ++++++++++++++++++++++++++++ AGENTS.md | 11 +++ 2 files changed, 116 insertions(+) create mode 100644 .claude/skills/merging-prs/SKILL.md diff --git a/.claude/skills/merging-prs/SKILL.md b/.claude/skills/merging-prs/SKILL.md new file mode 100644 index 0000000000..8959f52b7b --- /dev/null +++ b/.claude/skills/merging-prs/SKILL.md @@ -0,0 +1,105 @@ +--- +name: merging-prs +description: Merge a PR into main through the Trunk merge queue and babysit it until it lands. Enqueue with a "/trunk merge" comment, then poll the "Trunk Merge Queue" check run and the PR state until it is MERGED or FAILED, reporting the Trunk bot's failure reason if the PR is kicked out. Use when asked to merge a PR, "merge when ready", "land it", "ship it", or to babysit/watch a PR through the queue. Never use `gh pr merge` in this repo -- the queue is the only path into main. +allowed-tools: Bash(gh pr view:*), Bash(gh pr checks:*), Bash(gh pr comment:*), Bash(gh pr ready:*), Bash(gh api:*), Bash(sleep:*) +--- + +# Merge a PR through the Trunk merge queue + +Merges into `main` go **exclusively** through the [Trunk](https://trunk.io) merge +queue. `gh pr merge` and the GitHub merge button are blocked by branch ruleset. +To merge, you enqueue the PR with a comment, then watch it until Trunk lands it. + +When a developer says "merge this PR", "merge it when it's ready", "land it", +"ship it", or "babysit this PR", do the full loop below — enqueue **and** watch +to completion, reporting the outcome. See also [docs/merge-queue.md](../../../docs/merge-queue.md). + +`` below is the PR number. Resolve the repo slug once if you need it: +`REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)`. + +## 1. Preflight + +```bash +gh pr view --json state,isDraft,mergeable,reviewDecision,statusCheckRollup +``` + +- **Not open** (already merged/closed) → report and stop. +- **Draft** → it can't be merged. Ask the developer to confirm, then + `gh pr ready ` before continuing. Don't un-draft silently. +- **Failing required checks** (`statusCheckRollup`) → the queue will just reject + it. Report which checks are red and stop; fix them first. **Pending** checks + are fine — the queue waits for them. +- **Merge conflicts** (`mergeable == "CONFLICTING"`) → report and stop; rebase first. + +## 2. Enqueue + +```bash +gh pr comment --body "/trunk merge" +``` + +Within ~2 minutes, confirm Trunk picked it up — a check run whose name starts +with `Trunk Merge Queue` should appear on the head commit: + +```bash +SHA=$(gh pr view --json headRefOid -q .headRefOid) +gh api repos/$REPO/commits/$SHA/check-runs \ + --jq '.check_runs[] | select(.name | startswith("Trunk Merge Queue")) | {name, status, conclusion, details_url}' +``` + +If nothing appears after a couple of minutes, the developer may lack write +access or GitHub-comment commands may be disabled — report that and suggest the +`trunk-merge-queue-submit` label as a fallback. + +## 3. Poll until it lands + +Loop about every 60 seconds, up to ~45–60 minutes total. Each iteration: + +```bash +gh pr view --json state,mergedAt # MERGED -> success, stop +SHA=$(gh pr view --json headRefOid -q .headRefOid) +gh api repos/$REPO/commits/$SHA/check-runs \ + --jq '.check_runs[] | select(.name | startswith("Trunk Merge Queue")) | {status, conclusion, details_url}' +sleep 60 +``` + +- `state == "MERGED"` → done. Report success with the merge commit. +- Check run `status` moves `queued` → `in_progress` → `completed`. Report each + transition so the developer can follow along. +- Watch the **check run + PR state**, not `gh pr checks --watch`: the queue runs + CI on Trunk's own draft/`trunk-merge/**` branch, so this PR's own checks don't + reflect the queue's testing. +- Stop at the timeout with a status summary rather than looping forever. + +## 4. Handle failure + +If the check run completes with `conclusion == "failure"` (or the PR drops out +of the queue), Trunk kicks the PR and its bot comments with the failing +workflow. Read the newest comments and report the reason: + +```bash +gh pr view --comments | tail -n 40 +``` + +- If the failure is clearly caused by this PR **and** the fix is obvious, fix it, + push, wait for the PR's own checks to go green, and re-enqueue **once** with + `/trunk merge`. +- Otherwise stop and report the failure and the workflow link. Don't repeatedly + re-enqueue a red PR. + +## 5. Cancel + +If the developer asks to stop the merge: + +```bash +gh pr comment --body "/trunk cancel" +``` + +Confirm the check run reports cancelled. + +## Hard rules + +- **Never** run `gh pr merge` — it's blocked and it's not how this repo merges. +- **Never** force-push a branch while it is in the queue — it removes the PR + from the queue. +- Re-enqueue a failed PR **at most once** automatically; beyond that, hand back + to the developer. diff --git a/AGENTS.md b/AGENTS.md index c0343c6fa9..1e027ec6ad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -200,6 +200,17 @@ await boot(container); - `pnpm --filter code package|make`: package the Electron app. - `node scripts/check-host-boundaries.mjs`: verify host boundary allowlist. +## Merging PRs + +All merges into `main` go through the Trunk merge queue. Never run `gh pr merge` or click the GitHub merge button -- both are blocked by branch ruleset. + +- Enqueue: `gh pr comment --body "/trunk merge"`. Cancel: `gh pr comment --body "/trunk cancel"`. +- After enqueueing, babysit the PR until it merges or fails -- follow [`.claude/skills/merging-prs/SKILL.md`](./.claude/skills/merging-prs/SKILL.md) for the preflight, poll, and failure-handling loop. +- Queue progress is the `Trunk Merge Queue (main)` check run on the PR's head commit. On failure the Trunk bot comments with links to the failing workflows; fix, push, and re-enqueue. +- Never force-push a branch while it is in the queue -- it removes the PR from the queue. + +See [docs/merge-queue.md](./docs/merge-queue.md) for the full workflow and admin setup. + ## Code Style - Prefer local code over new dependencies for simple fixes. From fe16d17aabdcd690e374fee2d8558da95c74ad56 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Mon, 6 Jul 2026 15:00:24 -0400 Subject: [PATCH 2/2] docs(agents): drop redundant merge-queue doc pointer Remove the trailing "See docs/merge-queue.md" line from the Merging PRs section per review; the doc is already linked from the babysit-loop bullet. Generated-By: PostHog Code Task-Id: 2d321370-0c0e-4d63-89d7-e367ebd9ecee --- AGENTS.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1e027ec6ad..b9e3e21ac7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -209,8 +209,6 @@ All merges into `main` go through the Trunk merge queue. Never run `gh pr merge` - Queue progress is the `Trunk Merge Queue (main)` check run on the PR's head commit. On failure the Trunk bot comments with links to the failing workflows; fix, push, and re-enqueue. - Never force-push a branch while it is in the queue -- it removes the PR from the queue. -See [docs/merge-queue.md](./docs/merge-queue.md) for the full workflow and admin setup. - ## Code Style - Prefer local code over new dependencies for simple fixes.