// Guide for working with merge-train branches -- creating PRs, choosing the right base branch, understanding labels, handling failures, and bypassing checks.
| name | merge-trains |
| description | Guide for working with merge-train branches -- creating PRs, choosing the right base branch, understanding labels, handling failures, and bypassing checks. |
A merge train is an automated batching system (inspired by Rust rollups) that groups multiple PRs together for coordinated integration into the next branch. Instead of each PR going through the merge queue individually, teams push their PRs into a shared merge-train/* branch. Periodically, that branch is merged as a single unit into next.
| Branch | Team / Domain | Slack Channel |
|---|---|---|
merge-train/avm | AVM, barretenberg vm2 folder | #team-bonobos |
merge-train/barretenberg | Barretenberg folder, but not vm2 folder | #honk-team |
merge-train/ci | CI infrastructure / ci3 | #help-ci |
merge-train/docs | Documentation | #dev-rels |
merge-train/fairies | aztec-nr | #team-fairies |
merge-train/spartan | Spartan / infra / yarn-project sequencer and prover orchestration | #team-alpha |
next).merge-train/barretenberg).next) automatically accumulates your commit.merge-train/barretenberg -> next) is merged with a merge commit, preserving the individual squashed commits. This is why the ci-no-squash label is automatically applied.merge-train/docs run docs-only CI. PRs targeting merge-train/barretenberg run barretenberg-only CI. This avoids running the full test suite for domain-specific changes.merge-queue CI mode (4 parallel grind runs on AMD64 + 1 ARM64). merge-train/spartan uses the heavier merge-queue-heavy mode (10 grind runs).github.run_id), so multiple CI runs can proceed in parallel without cancelling each other.Two options from the merge-train-readme.md:
Option 1: Direct Fix -- Merge-train branches are protected, so you cannot push directly. Instead, create a PR targeting the merge-train branch with your fix, add the ci-skip label to skip CI, and use GitHub's "Merge without waiting for requirements to be met" button (bypass merge) to force-merge it. All users have bypass merge permission. Important: If your fix resolves a conflict from a next merge, use the merge commit method (not squash) to preserve the merge resolution.
Option 2: Fix in Next -- Merge a revert or workaround into next. The fix will auto-propagate to the merge-train via the merge-train-next-to-branches workflow. Best when the root cause is in next or multiple trains are affected.
The auto-merge script will not enable auto-merge if the last merge-queue CI run for the PR concluded with failure or cancelled. Someone needs to either fix the issue (via a PR to the merge-train branch, as described in Option 1 above) or force-merge.
When merging next into a train branch causes conflicts, the merge-next.sh script:
next commit listing the conflicted filesnext into the train branch (resolving conflicts locally), then force-merging it with ci-skip and the merge commit method (not squash) to preserve the merge resolutionIf the user needs to bypass CI checks for their merge-train PR (e.g., a known flaky failure, an urgent merge, or CI infrastructure issues):
next.ci-skip label: Apply the ci-skip label to the merge-train PR. This causes CI to skip entirely. Use: gh pr edit <PR_NUMBER> --add-label ci-skipImportant: Only do this when the user explicitly asks to bypass checks. Always confirm first since it skips all CI validation.
A related system exists for backport branches (backport-to-*). These use the same auto-merge mechanism but with different settings:
backport-to-Run realistic Chonk (client IVC) benchmarks using pinned protocol inputs. Covers native and WASM proving, per-circuit breakdowns, BB_BENCH instrumentation, and profiling code augmentation. Use when asked to benchmark, profile, or measure Chonk proving performance.
Run the Chonk (client-IVC) prover on the remote EC2 and collect Perfetto-compatible JSON traces. Supports both native and WASM runtimes. Generates a one-click Perfetto UI link for visual analysis. Use when asked to profile, trace, or visualize Chonk proving performance.
Run benchmarks on the dedicated remote EC2 benchmarking machine for noise-free, single-run results. Handles env var validation, lock management, binary transfer, and result collection. Use with /benchmark-chonk or any BB benchmark target.
Analyze source-file changes referenced by documentation, update affected docs when needed, and report documentation reference updates for a PR.
Build and update the developer documentation site for a new release
Reference for merge-train automation internals -- workflows, scripts, CI integration, and configuration. Use when modifying or debugging merge-train infrastructure.