Skip to main content
The merge queue provides controlled, safe merging of pull requests with intelligent conflict prediction, automated testing, priority handling, and batch optimization.

​
Overview

The merge queue:
  • Prevents merge conflicts by analyzing PRs and determining optimal merge order
  • Tests PRs before merging to prevent broken builds
  • Batches multiple PRs for efficient CI usage with automatic bisection on failure
  • Handles priority ordering with customizable priorities (0-100)
  • Auto-rebases PRs to stay up-to-date with the target branch
  • Provides detailed status and statistics

​
How It Prevents Conflicts

The merge queue uses an intelligent algorithm to prevent merge conflicts:

​
1. PR Analysis

When a PR is added to the queue, the system analyzes: 
Files Changed:      src/api/users.ts, src/db/schema.ts
Directories:        src/api, src/db, src
Conflict-Prone:     src/db/schema.ts (schema file)
Change Size:        +150 / -30 lines
Conflict-prone areas are automatically identified:
  • Lock files (package-lock.json, yarn.lock, pnpm-lock.yaml)
  • Generated files (*.generated.ts)
  • Schema and migration files
  • High-churn files (100+ lines changed)

​
2. Conflict Prediction

Before processing, the queue predicts conflicts between all PR pairs: 
PR #1 vs PR #2:
  - Direct file overlap: src/api/users.ts → +20 conflict score
  - Same directory: src/api → +2 conflict score
  - Both touch schema file → +30 conflict score
  - Conflict probability: 52%

​
3. Optimal Ordering

The queue uses a greedy algorithm to determine the safest merge order: 
Queue: [PR #1, PR #2, PR #3, PR #4]

Conflict Matrix:
       #1    #2    #3    #4
  #1   -    0.52  0.10  0.05
  #2  0.52   -    0.30  0.15
  #3  0.10  0.30   -    0.80
  #4  0.05  0.15  0.80   -

Optimal Order: [#4, #1, #2, #3]
  - #4 first: lowest total conflict risk
  - #1 next: conflicts mainly with #2 (not yet merged)
  - #2 next: can now resolve against #4 and #1
  - #3 last: high conflict with #4, but #4 already merged

​
4. Speculative Merging

The queue performs merges in an isolated worktree:
  1. Create temporary branch from target
  2. Cherry-pick commits in optimal order
  3. If conflict occurs, try reordering or fall back to merge commit
  4. Push speculative merge for CI testing
  5. Only update target branch if CI passes

​
5. Batch Processing with Bisection

When batching multiple PRs, if one fails: 
Batch: [#1, #2, #3, #4, #5] → FAILED

Bisect:
  [#1, #2] → SUCCESS
  [#3, #4, #5]
    [#3] → FAILED (identified!)
    [#4, #5] → SUCCESS

Result: #1, #2, #4, #5 merged; #3 needs fixes

​
Quick Start

# Add current PR to merge queue
wit merge-queue add

# Add specific PR with priority
wit merge-queue add 123 --priority 50

# Check queue status
wit merge-queue status

# List all queued PRs
wit merge-queue list

​
Commands

​
Add to Queue

# Add current branch's PR
wit merge-queue add

# Add specific PR
wit merge-queue add 123

# Add with priority (0-100, higher = more urgent)
wit merge-queue add 123 --priority 50

​
Remove from Queue

# Remove current branch's PR
wit merge-queue remove

# Remove specific PR
wit merge-queue remove 123

​
Check Status

$ wit merge-queue status

Merge Queue Status for PR #123

  Position: 3 of 5
  State: pending
  Estimated wait: ~15 minutes
  Conflict score: 23 (low)

​
List Queue

$ wit merge-queue list

Merge Queue for myrepo:main

  #  PR       State        Priority  Conflict  Title
  ─────────────────────────────────────────────────────
  1  #125     ready        80        12        Implement caching
  2  #123     testing      50        45        Add authentication
  3  #127     pending      50        23        Fix database issue
  4  #128     pending      20        67        Update dependencies

​
Queue Statistics

$ wit merge-queue stats

Merge Queue Statistics for myrepo:main

  Pending:           3
  Processing:        1
  Merged today:      12
  Failed today:      2
  Avg merge time:    8 minutes

​
Configuration

View or update merge queue settings: 
# View current config
$ wit merge-queue config

Merge Queue Configuration for myrepo:main

  Enabled:           yes
  Strategy:          adaptive
  Auto-merge mode:   auto
  Max batch size:    5
  Min wait (sec):    60
  Auto rebase:       yes
  Delete branches:   yes
  Required checks:   test, build, lint

Update with: wit merge-queue config --strategy <strategy>

# Update settings
wit merge-queue config --strategy adaptive
wit merge-queue config --batch-size 3
wit merge-queue config --auto-rebase
wit merge-queue config --no-delete-branch

​
Enable/Disable

# Enable for main branch
wit merge-queue enable

# Enable for specific branch
wit merge-queue enable --branch production

# Disable
wit merge-queue disable

​
Queue States

PRs in the queue go through these states:
StateDescription
pendingWaiting in queue for earlier PRs
preparingBuilding speculative merge commit
testingCI tests running on speculative merge
readyTests passed, ready to merge
mergingCurrently updating target branch
completedSuccessfully merged
failedTests failed or merge conflict
cancelledRemoved from queue

​
Strategies

The merge queue supports different strategies:

​
Sequential

Tests and merges one PR at a time. Safest but slowest. 
wit merge-queue config --strategy sequential
Best for: Critical branches, low-volume repos

​
Optimistic

Groups multiple PRs together for testing. Uses bisection on failure. 
wit merge-queue config --strategy optimistic --batch-size 5
Best for: High-volume repos with good CI Analyzes conflicts and determines optimal merge order, then batches. 
wit merge-queue config --strategy adaptive
Best for: Most use cases - balances safety and speed

​
Auto-Merge Modes

Control when the queue processes:

​
Auto (Default)

Queue processes automatically when PRs are ready. 
wit merge-queue config --auto-merge-mode auto

​
Manual

Wait for explicit trigger to process. 
wit merge-queue config --auto-merge-mode manual

# Then trigger manually
wit merge-queue process

​
Scheduled

Only process during specific time windows. 
wit merge-queue config --auto-merge-mode scheduled \
  --merge-window-start 9 \
  --merge-window-end 17 \
  --merge-window-days 1,2,3,4,5  # Monday-Friday

​
Priority System

Higher priority PRs are processed first: 
# Low priority (default: 50)
wit merge-queue add 123

# High priority (urgent fix)
wit merge-queue add 123 --priority 80

# Critical (hotfix)
wit merge-queue add 123 --priority 100
Within the same priority level, conflict analysis determines order.

​
Configuration Options

OptionDescriptionDefault
--strategyMerge strategy (sequential, optimistic, adaptive)adaptive
--batch-sizeMaximum PRs per batch5
--min-waitMinimum seconds before processing60
--auto-rebaseAuto-rebase PRs before testingtrue
--delete-branchDelete branch after mergetrue
--auto-merge-modeWhen to process (auto, manual, scheduled)auto
--required-checksCI checks that must passnone

​
Web UI Integration

The merge queue is integrated into the PR page:

​
From the Action Card

  • Merge Now: Direct merge to branch (bypasses queue)
  • Add to Queue: Queue for automated, conflict-free merging
  • Add with Priority: Queue with high priority (jumps ahead)

​
Queue Status

When a PR is in the queue, the action card shows:
  • Current position and state
  • Progress bar for active states
  • Estimated wait time
  • Remove from queue option
A compact status indicator shows:
  • Queue position
  • Processing state
  • Link to queue settings

​
Workflow Example

​
Adding PRs to Queue

# Create and push a PR
wit checkout -c feature/new-feature
# ... make changes ...
wit commit -m "Add new feature"
wit push -u origin feature/new-feature
wit pr create

# Add to merge queue
wit merge-queue add

​
Monitoring Queue Progress

# Check your PR's position
wit merge-queue status

# Watch the full queue
wit merge-queue list

# Check if there are any issues
wit merge-queue stats

​
Handling Failures

If your PR fails in the queue: 
# Check what happened
$ wit merge-queue status 123

PR #123 failed in merge queue
  Reason: Merge conflict in src/api/users.ts
  
Fix the issue and re-add:
  wit merge-queue add 123

# Fix the conflict
wit checkout feature/my-branch
git fetch origin main
git rebase origin/main
# ... resolve conflicts ...
wit push --force-with-lease
wit merge-queue add

​
JSON Output

For scripting and automation: 
# Queue status as JSON
wit merge-queue status --json

# List as JSON
wit merge-queue list --json

# Stats as JSON
wit merge-queue stats --json

​
Integration with CI/CD

The merge queue integrates with wit’s built-in CI: 
# .wit/workflows/ci.yml
name: CI
on:
  pull_request:
  merge_queue:  # Triggered by merge queue

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
      - run: npm run build

​
Required Checks

Configure which CI checks must pass: 
# Set required checks
wit merge-queue config --required-checks "test,build,lint"

# The merge queue will wait for these checks to pass

​
Best Practices

​
For Fast Merges

  • Keep PRs small and focused
  • Ensure CI is fast and reliable
  • Use the adaptive strategy for high-volume repos

​
For Safety

  • Enable auto-rebase to catch conflicts early
  • Require status checks
  • Use the sequential strategy for critical branches

​
For Teams

  • Set clear priority guidelines (80+ for urgent, 50 for normal)
  • Monitor queue statistics regularly
  • Use scheduled mode to avoid merges during critical periods

​
Technical Details

​
Conflict Score Calculation

Score = 0

For each file in PR1:
  If same file in PR2: Score += 20
  
For each directory in PR1:
  If same directory in PR2: Score += 2
  
For each conflict-prone file in PR1:
  If same file in PR2: Score += 30

Probability = min(1, Score / 100)

​
Optimal Order Algorithm

  1. Build NxN conflict matrix for N PRs
  2. Greedy selection: pick PR with lowest sum of conflicts
  3. Repeat until all PRs ordered
  4. PRs touching unique files go first
  5. PRs touching shared files go last (built on stable base)

​
Speculative Merge Process

  1. Create isolated git worktree from target branch
  2. For each PR in optimal order:
    • Try cherry-picking each commit
    • If fails, fall back to merge commit
    • If still fails, report failure
  3. Push speculative merge to temp branch
  4. Run CI on speculative merge
  5. If CI passes, fast-forward target branch

​
Requirements

The merge queue requires:
  • wit server running (wit serve)
  • Database connected (PostgreSQL)
  • CI/CD configured (optional but recommended)
  • Branch protection enabled (recommended)