SETUP_GUIDE.md

Merge Queue Setup Guide

This guide walks you through setting up the merge queue for your repository.

Prerequisites

• Repository must be on GitHub
• You need admin access to the target repository
• Node.js 20.x installed (for local development/testing)

Part 1: Merge Queue Repository Setup

Step 1: Create the Merge Queue Repository

If you haven't already:

1. Create a new repository on GitHub:

   • Name: merge-queue
   • Visibility: Private (recommended) or Public
   • Initialize with README: No (we have our own)

2. Push the merge-queue code:

   cd /path/to/merge-queue
   git remote add origin [email protected]:BloomAndWild/merge-queue.git
   git push -u origin main

Step 2: Build and Tag a Release

1. Install dependencies and build:

   npm install
   npm run build

2. Create initial release:

   git tag v1.0.0
   git push origin v1.0.0

3. Verify the tag appears on GitHub under Releases

That's it for the merge-queue repo — no state branch or additional setup needed.

Part 2: Target Repository Setup

Step 1: Create a GitHub App

The merge queue authenticates via a GitHub App. Installation tokens are generated automatically on each workflow run — no manual rotation, no user seat required, and a better audit trail.

1. Create the GitHub App

1. Go to your organization settings → Developer settings → GitHub Apps → New GitHub App (or for a personal account: Settings → Developer settings → GitHub Apps)

2. Configure the app:

   • GitHub App name: Merge Queue (or any unique name)
   • Homepage URL: Your merge-queue repository URL
   • Webhook: Uncheck "Active" (not needed)

3. Under Repository permissions, set:

   Permission	Access	Why
   Pull requests	Read & Write	Merge PRs, post comments, manage labels
   Contents	Read & Write	Update branches, delete merged branches
   Actions	Read & Write	Trigger workflow self-dispatch
   Commit statuses	Read	Read CI status results for validation
   Checks	Read	Read check run results for validation
   Metadata	Read	Required by default

4. Under Where can this GitHub App be installed?, select "Only on this account"

5. Click "Create GitHub App"

6. Note the App ID shown on the app's settings page

7. Scroll down to Private keys and click "Generate a private key" — a .pem file will download automatically

2. Install the App

1. On the app's settings page, click "Install App" in the sidebar

2. Select your organization (or personal account)

3. Choose "Only select repositories" and pick the repositories that need the merge queue

4. Click "Install"

3. Add Secrets and Variables

In each target repository:

1. Go to Settings → Secrets and variables → Actions

2. Under the Variables tab, click "New repository variable":

   • Name: MERGE_QUEUE_APP_ID
   • Value: The App ID from step 6 above

3. Under the Secrets tab, click "New repository secret":

   • Name: MERGE_QUEUE_APP_PRIVATE_KEY
   • Value: Paste the full contents of the .pem file you downloaded

Step 2: Add Workflow Files

Copy the example workflows from examples/target-repo-workflows/.

1. Create .github/workflows/ directory if it doesn't exist:

   mkdir -p .github/workflows

2. Copy the three workflow files from the merge-queue repository:

   Using curl

   cd .github/workflows/
   BASE=https://raw.githubusercontent.com/BloomAndWild/merge-queue/main/examples/target-repo-workflows
   
   curl -O "$BASE/merge-queue-entry.yml"
   curl -O "$BASE/merge-queue-manager.yml"
   curl -O "$BASE/merge-queue-remove.yml"

   Manual copy

   • Copy files from examples/target-repo-workflows/
   • Paste into your repo's .github/workflows/

3. Update the workflow files:

   Find and replace BloomAndWild with your GitHub organization/username:

   # Before
   uses: BloomAndWild/merge-queue/src/actions/add-to-queue@v1
   
   # After
   uses: mycompany/merge-queue/src/actions/add-to-queue@v1

4. Customize configuration (optional):

   Edit the workflow files to adjust settings like:

   • merge-method: squash, merge, or rebase
   • block-labels: Labels that prevent queueing
   • update-timeout-minutes: How long to wait for tests

   To customise the trigger label, set the MERGE_QUEUE_LABEL repository variable instead of editing workflow files — the example workflows already reference it with a fallback to ready.

Step 3: Create Labels

The queue uses several labels. Create them in your repository.

Tip: The trigger label defaults to ready. To use a different name, set the MERGE_QUEUE_LABEL repository variable (Settings → Secrets and variables → Actions → Variables) and create a label with that name instead.

1. Go to Issues → Labels → New label

2. Create these labels:

   Label	Color	Description
   ready (or your custom trigger label)	#0e8a16 (green)	Add this to queue a PR
   queued-for-merge	#fbca04 (yellow)	PR is waiting in queue
   merge-processing	#1d76db (blue)	PR is being processed
   merge-updating	#5319e7 (purple)	Branch is being updated
   merge-queue-failed	#d73a4a (red)	Validation or tests failed
   merge-queue-conflict	#b60205 (dark red)	Merge conflict detected

   Quick create script:

   # Requires GitHub CLI (gh)
   # Replace "ready" with your custom label name if you set MERGE_QUEUE_LABEL
   gh label create "ready" --color "0e8a16" --description "Add this to queue a PR"
   gh label create "queued-for-merge" --color "fbca04" --description "PR is waiting in queue"
   gh label create "merge-processing" --color "1d76db" --description "PR is being processed"
   gh label create "merge-updating" --color "5319e7" --description "Branch is being updated"
   gh label create "merge-queue-failed" --color "d73a4a" --description "Validation or tests failed"
   gh label create "merge-queue-conflict" --color "b60205" --description "Merge conflict detected"

Step 4: Commit and Push

git add .github/workflows/
git commit -m "Add merge queue workflows"
git push origin main

Part 3: Testing

Test 1: Create a Test PR

1. Create a simple PR (fix typo, update README, etc.)

2. Get it approved (ensure it has required approvals)

3. Ensure all checks are passing

4. Add the trigger label (default: ready)

5. Watch for:

   • ✅ queued-for-merge label added
   • ✅ Comment confirming addition to queue

Test 2: Verify Queue Processing

1. Wait up to 5 minutes (or manually trigger the queue-manager workflow)

2. Watch for:

   • ✅ merge-processing label added
   • ✅ PR automatically merged
   • ✅ Branch deleted (if configured)
   • ✅ Success comment posted

Test 3: Test Failure Handling

1. Create a PR with failing tests

2. Add the trigger label (default: ready)

3. Verify:

   • ✅ merge-queue-failed label added
   • ✅ Comment explaining failure
   • ✅ PR removed from queue

Test 4: Test Branch Update

1. Create PR #1 and merge it manually

2. Create PR #2 (now behind master)

3. Add the trigger label (default: ready) to PR #2

4. Verify:

   • ✅ Branch automatically updated
   • ✅ Tests re-run
   • ✅ PR merges after tests pass

Part 4: Configuration

Customizing Queue Behavior

Edit .github/workflows/merge-queue-entry.yml and merge-queue-manager.yml:

with:
  # Merge method
  merge-method: squash     # Change to 'merge' or 'rebase'

  # Branch deletion
  delete-branch-after-merge: true  # Change to false to keep branches

  # Blocking labels
  block-labels: do-not-merge,wip,draft  # Add custom labels

  # Test timeout
  update-timeout-minutes: 30  # Increase for slow test suites

Troubleshooting

Issue: "Unable to resolve action" error

Cause: Incorrect action reference syntax or private repo access not enabled

Solution:

1. Ensure the path comes before @ref in action references:

   # Correct
   uses: BloomAndWild/merge-queue/src/actions/add-to-queue@v1
   
   # Wrong — GitHub treats everything after @ as the version
   uses: BloomAndWild/merge-queue@v1/src/actions/add-to-queue

2. If the merge-queue repository is private, enable access from other repos in the same organisation: go to the merge-queue repo → Settings → Actions → General → "Access" section → select "Accessible from repositories in the organisation"

Issue: Workflows don't run

Cause: App permissions or workflow file errors

Solution:

1. Check Actions tab for error messages
2. Validate workflow YAML syntax
3. Verify MERGE_QUEUE_APP_ID variable and MERGE_QUEUE_APP_PRIVATE_KEY secret exist
4. Confirm the GitHub App is still installed on the repository

Issue: "Permission denied" errors

Cause: Insufficient permissions on the GitHub App

Solution:

1. Check the App's permission settings match the table in Step 1
2. Verify the App is installed on this specific repository

Issue: PRs not merging

Cause: Validation failures or queue stuck

Solution:

1. Check PR comments for error details
2. View Actions logs in target repository
3. Search for PRs with queued-for-merge or merge-processing labels to see queue state
4. Manually trigger queue-manager workflow

Issue: Tests timeout

Cause: Tests take longer than configured timeout

Solution:

• Increase update-timeout-minutes in workflows
• Optimize test suite performance

Monitoring

View Queue State

Search for open PRs with queue labels to see the current state:

• Waiting: PRs with queued-for-merge label
• Processing: PRs with merge-processing label
• Failed: PRs with merge-queue-failed or merge-queue-conflict label

View Action Logs

1. Go to target repository → Actions tab

2. Select workflow run

3. View logs for debugging

Maintenance

Private Key Rotation

No manual token rotation is needed — installation tokens are generated automatically on each workflow run and expire after one hour.

If you need to rotate the App's private key (e.g. as part of a security policy), generate a new one on the App settings page, update the MERGE_QUEUE_APP_PRIVATE_KEY secret in each target repository, then optionally revoke the old key.

Updating Merge Queue

When new version is released:

1. Pull latest changes to merge-queue repo:

   git pull origin main

2. Tag new release:

   git tag v1.1.0
   git push origin v1.1.0

3. Update workflow files in target repos:

   # Change from
   uses: BloomAndWild/merge-queue/src/actions/[email protected]
   
   # To
   uses: BloomAndWild/merge-queue/src/actions/[email protected]

Best Practices

1. Security

   • Installation tokens are short-lived, auto-generated, and not tied to a user account
   • Install the GitHub App only on repositories that need the merge queue
   • Restrict the "Where can this GitHub App be installed?" setting to your own account
   • Never commit private keys or secrets to git

2. Testing

   • Test queue with dummy PRs first
   • Monitor first few real PRs closely
   • Keep eye on Action logs initially

3. Configuration

   • Start with default settings
   • Adjust based on team workflow
   • Document custom configurations

4. Communication

   • Inform team about merge queue
   • Document in repository README
   • Create team guide for using the trigger label (default: ready)

Next Steps

• Read ARCHITECTURE.md to understand internals
• Check CONTRIBUTING.md for development guidelines
• Join discussions for questions and feedback

Support

• Documentation: Check /docs directory
• Issues: Report bugs on GitHub
• Questions: Use GitHub Discussions