Set up a GitHub merge queue with Paradime Turbo CI

A GitHub merge queue tests pull requests in the exact state they will be in after merging, batching multiple PRs together so integration issues are caught before merge rather than after. This guide connects a merge queue to a Paradime Bolt Turbo CI schedule.

Prerequisites

Repository admin permissions.
A Paradime Bolt Turbo CI schedule configured.
Paradime API credentials set in your GitHub repository secrets.
A CI/CD workflow already configured, with required status checks defined for the repository.

Steps

Create a merge queue workflow

Create a new GitHub Actions workflow file (for example, .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: the merge_group event runs the workflow 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.

Configure repository settings

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

Enable merge queue:
- Check Require merge queue.
- Configure merge queue settings for your needs:
  - Merge method: choose squash, merge commit, or rebase.
  - Build concurrency: set the maximum number of PRs to test simultaneously.
  - Merge queue grouping: configure batching behavior.
Configure required status checks:
- Go to Settings → Branches.
- Edit the branch protection rule for the main branch.
- Add Paradime Turbo CI as a required status check.

Set the status check source to any source, because the check comes from both Paradime and the GitHub Actions workflow.

GitHub required status checks with Paradime Turbo CI added and source set to any source

You know the merge queue is working when adding a PR to the queue triggers a Paradime Turbo CI run against a temporary merge commit, and the PR merges only after that check passes. If the workflow never runs, confirm the merge_group trigger is configured and the workflow is listed as a required check.

How it works

PR creation: a developer creates a pull request.
Queue addition: when ready to merge, the PR is added to the merge queue.
Batch testing: GitHub creates a temporary merge commit combining the PR with the target branch.
CI execution: the merge queue workflow runs against this temporary commit.
Merge decision: if tests pass, the PR is automatically merged; if they fail, the PR is removed from the queue and the developer is notified.

Multiple PRs can be batched and tested together for efficiency, failed PRs are removed without affecting others, and PRs are processed in the order they were added.

Best practices

Keep tests fast: optimize merge queue workflows for speed and use dependency caching.
Run in parallel: structure jobs to run in parallel where possible.
Require reviews: combine the merge queue with required code reviews and comprehensive branch protection rules.
Limit status checks: only require essential checks to avoid bottlenecks.
Set clear guidelines: establish when to use the merge queue versus a direct merge, monitor queue status, and notify the team when the queue is blocked.

Troubleshooting

Workflow not triggering

Verify the 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 the schedule name matches your Turbo CI configuration.
Check that the API endpoint and credentials are correct.

Queue bottlenecks

Review concurrency settings.
Optimize workflow performance.
Consider adjusting batch size settings.

For advanced configurations, consult the GitHub merge queue documentation.

Next steps

Protect the main branch on GitHub

Require pull requests and reviews before merging to main.

Sign your commits

Add SSH-based commit signing for verified commits.

Connect a GitHub repository

Set up your repository connection in Paradime.

Version control in the Code IDE

How commits, branches, and pushes work in Paradime.

Foundations

Automate with AI agents

Set up & configure

Orchestrate data pipelines

Migrate to Paradime

Develop in Paradime

Learn dbt™

Set up a GitHub merge queue with Paradime Turbo CI

Steps

How it works

Best practices

Troubleshooting

Next steps

Protect the main branch on GitHub

Sign your commits

Connect a GitHub repository

Version control in the Code IDE

​Steps

​How it works

​Best practices

​Troubleshooting

​Next steps

Protect the main branch on GitHub

Sign your commits

Connect a GitHub repository

Version control in the Code IDE

Steps

How it works

Best practices

Troubleshooting

Next steps