GitHub Merge Queue

Overview

GitHub Merge Queue is a feature that helps maintain code quality and prevent integration issues by automatically testing pull requests together before merging them into the main branch. This documentation covers how to set up and configure merge queue with CI/CD workflows.

What is Merge Queue?

Merge Queue ensures that:

• Pull requests are tested in the exact state they'll be in after merging

• Multiple PRs can be batched and tested together

• Failed tests prevent problematic code from reaching the main branch

• Integration issues are caught before merge, not after

Prerequisites

Before setting up merge queue, ensure you have:

• Repository admin permissions

• A Paradime Bolt Turbo CI schedule configured

• Paradime API credentials set in your GitHub repo

• A CI/CD workflow already configured

• Required status checks defined for your repository

Setup Process

Step 1: Create a Merge Queue Workflow

Create a new GitHub Actions workflow file (e.g., .github/workflows/merge-queue-ci.yml) that triggers on merge_group events:

name: Paradime Turbo CI
on:
  merge_group:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  paradime-turbo-ci:
    name: Paradime Turbo CI
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install paradime-io
        run: |
          python -m pip install --upgrade pip
          pip install paradime-io==4.6.0

      - name: Run Paradime CLI command
        env:
          PARADIME_API_ENDPOINT: ${{ secrets.PARADIME_API_ENDPOINT }}
          PARADIME_API_KEY: ${{ secrets.PARADIME_API_KEY }}
          PARADIME_API_SECRET: ${{ secrets.PARADIME_API_SECRET }}
          SCHEDULE_NAME: >-
            <YOUR_TURBO_CI_SCHEDULE_NAME>
        run: paradime bolt run "${{ env.SCHEDULE_NAME }}" --branch "${{ github.sha }}" --wait

Key Configuration Points:

• Trigger: merge_group event ensures the workflow runs when PRs are added to the merge queue

• Concurrency: Prevents multiple instances of the same workflow from running simultaneously

• Schedule Name: Replace YOUR_TURBO_CI_SCHEDULE_NAME with your actual Turbo CI schedule name

• Secrets: Ensure all required API credentials are configured in repository secrets

Step 2: Configure Repository Settings

Navigate to your repository's Settings → General → Pull Requests:

1. Enable Merge Queue:

   • Check "Require merge queue"

   • Configure merge queue settings according to your needs:

     • Merge method: Choose squash, merge commit, or rebase

     • Build concurrency: Set maximum number of PRs to test simultaneously

     • Merge queue grouping: Configure batching behavior

2. Configure Required Status Checks:

   • Go to Settings → Branches

   • Edit your branch protection rule for the main branch

   • Add "Paradime Turbo CI" as a required status check

   • ⚠️ Important: Set the source to "any source" since the status check comes from both Paradime and the GitHub Actions workflow

Workflow Behavior

How It Works

1. PR Creation: Developer creates a pull request

2. Queue Addition: When ready to merge, PR is added to the merge queue

3. Batch Testing: GitHub creates a temporary merge commit combining the PR with the target branch

4. CI Execution: The merge queue workflow runs against this temporary commit

5. Merge Decision:

   • ✅ If tests pass: PR is automatically merged

   • ❌ If tests fail: PR is removed from queue and developer is notified

Queue Management

• Automatic Batching: Multiple PRs can be tested together for efficiency

• Failure Handling: Failed PRs are automatically removed without affecting others

• Priority: PRs are processed in the order they were added to the queue

Best Practices

Workflow Design

• Keep Tests Fast: Merge queue workflows should be optimized for speed

• Use Caching: Implement dependency caching to reduce build times

• Parallel Execution: Structure jobs to run in parallel where possible

• Clear Naming: Use descriptive job and step names for easier debugging

Repository Configuration

• Require Reviews: Combine merge queue with required code reviews

• Branch Protection: Use comprehensive branch protection rules

• Status Checks: Only require essential checks to avoid bottlenecks

• Documentation: Keep team documentation updated on merge queue usage

Team Workflow

• Clear Guidelines: Establish when to use merge queue vs. direct merge

• Monitor Queue: Regularly check queue status and resolve issues promptly

• Communication: Notify team members when queue is blocked

Troubleshooting

Common Issues

Workflow Not Triggering

• Verify merge_group trigger is correctly configured

• Check that the workflow file is in the correct location

• Ensure branch protection rules include the workflow as a required check

Status Check Failures

• Confirm all required secrets are configured

• Verify schedule name matches your Turbo CI configuration

• Check API endpoint and credentials are correct

Queue Bottlenecks

• Review concurrency settings

• Optimize workflow performance

• Consider adjusting batch size settings

Debugging Tips

• Check the "Actions" tab for detailed workflow logs

• Review merge queue status in the PR interface

• Monitor repository insights for queue performance metrics

GitHub Merge Queue provides a robust solution for maintaining code quality while enabling efficient team collaboration. By following this setup guide and best practices, your team can implement a reliable merge process that scales with your development workflow. For additional support or advanced configurations, consult the GitHub Documentation or reach out to your DevOps team.