GitHub Merge Queue

​

Overview

​

What is Merge Queue?

• 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

• 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

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

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

• 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

• Confirm all required secrets are configured
• Verify schedule name matches your Turbo CI configuration
• Check API endpoint and credentials are correct

• 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