Merging Pr Stack

You are a staff engineer merging a stack of stacked jj branches into main via GitHub's merge queue.

Process

Phase 1: Pre-merge checks

1. List the PR stack from base to tip. If not provided, infer from jj log and gh pr list:

``bash jj log --revisions 'ancestors(@, 10) & bookmarks()' --no-graph gh pr list --state open ` Order them base-first (the PR closest to main` merges first).

1. Check CI on the base PR:

``bash gh pr checks ``

• If all checks pass: proceed to Phase 2.
• If checks are failing: stop and report which checks failed. Do not proceed until CI is green.

Phase 2: Merge the base PR

1. Add the base PR to the merge queue (preferred) or merge directly:

``bash gh pr merge --merge --auto ``

• If the repo uses a merge queue, --auto will queue it automatically.
• If merge queue is not configured, this merges immediately.

1. Poll merge queue status via GraphQL until the entry is merged or errored:

``bash gh api graphql -f query=' query($owner: String!, $repo: String!, $number: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $number) { mergeQueueEntry { state position estimatedTimeToMerge } } } } ' -f owner= -f repo= -F number= ``

• state values: QUEUED, AWAITING_CHECKS, MERGEABLE, MERGED, FAILED, LOCKED
• If state is MERGED: proceed to Phase 3.
• If state is FAILED or LOCKED: stop and report the failure. Do not proceed with the rest of the stack.
• If state is QUEUED or AWAITING_CHECKS: wait ~30s and poll again. Repeat until terminal state.
• If no mergeQueueEntry (not using merge queue): check gh pr view --json state — if state is MERGED, proceed.

Phase 3: Rebase remaining stack onto main

1. Fetch the updated remote:

``bash jj git fetch ``

1. Rebase remaining stack branches onto main@origin:

``bash jj rebase -s -d main@origin ``

• Repeat for each remaining branch in the stack, base-first.
• Alternatively, if the entire remaining stack is contiguous:

``bash jj rebase -s -d main@origin `` jj will automatically carry descendants along.

1. Resolve conflicts if any appear (jj log shows ! markers):

• For each conflicted revision:

1. jj new — create resolution on top
2. Edit conflicted files to resolve >> markers
3. jj squash — fold the resolution into the conflicted revision

• Repeat until jj log shows no ! markers.

1. Verify base retargeting — the next PR's base should now target main:

``bash gh pr view --json baseRefName ``

• If baseRefName is still the old merged branch: update it:

``bash gh pr edit --base main ``

1. Push the rebased branches:

``bash jj git push --bookmark --bookmark ... `` Push all remaining stack branches in one command.

Phase 4: Repeat for each remaining PR

1. Return to Phase 1 for the new base PR (previously the second PR in the stack). Repeat Phases 1–3 until all PRs in the stack are merged.

Completion Criteria

• All PRs in the stack are merged into main
• jj git fetch shows no pending stack branches diverging from main@origin
• All merge queue entries finished with MERGED state
• No ! conflict markers remain in jj log

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jack-michaud
• Source: jack-michaud/faire
• License: MIT

Install and usage instructions live in the source repository linked above.