How To Set Up Merge Queues in GitHub Actions

Managing pull requests (PRs) efficiently in a collaborative development environment is crucial to ensure that the codebase remains stable and conflict-free. With GitHub Actions, automating the PR merging process with merge queues can help streamline your workflow, reduce manual intervention, and ensure that only PRs that pass all necessary checks are merged into the main branch.

In this guide, we’ll show you how to set up merge queues in GitHub Actions to streamline your workflow, reduce merge conflicts, and enforce consistent quality standards

What is a Merge Queue?

A merge queue automates the process of merging pull requests into a busy branch while maintaining the stability of the target branch. This system ensures that PRs meet the necessary checks before they are merged. It helps streamline the workflow by eliminating the need for PR authors to manually update their branches or wait for status checks to pass before merging.

Once a PR passes all required checks, a repository administrator can add it to the merge queue. The queue groups PRs together and verifies that they pass the required checks against the most recent version of the target branch and any other PRs already in the queue.

Why Set Up Merge Queues in GitHub Actions?

• Automated Merging: Merge queues automatically merge PRs that pass all checks, reducing manual intervention.
• Prevent Merge Conflicts: Queuing PRs allows you to merge them one at a time, minimizing conflicts.
• Enforce Consistent Standards: Ensure only PRs that pass all tests and code quality checks are merged.
• Streamlined Collaboration: Simplifies managing a large number of PRs, improving team efficiency.

How to Set Up Merge Queues in GitHub Actions: Step by Step Process

Step 1: Create a New Workflow for the Merge Queue

To set up a merge queue in GitHub Actions, you'll need to create a new workflow file. This workflow will define the jobs responsible for checking PR labels, adding PRs to the queue, and processing the queue.

1. Navigate to your GitHub repository.
2. Create a new workflow file under .github/workflows/ in your repository (e.g., merge-queue.yml).

Here's an example of how to structure the workflow:

name: Merge Queue

on:
  pull_request:
    types:
      - labeled
      - opened
      - synchronize

jobs:
  enqueue:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the code
        uses: actions/checkout@v3

      - name: Verify PR Label and Checks
        run: |
          if [[ "${{ github.event.pull_request.labels }}" != *"ready-to-merge"* ]]; then
            echo "PR is not labeled as ready to merge. Exiting..."
            exit 1
          fi
          echo "All checks passed and PR is labeled. Adding to merge queue."

      - name: Add PR to Merge Queue
        run: |
          echo "${{ github.event.pull_request.number }}" >> .github/merge-queue.txt

  process-queue:
    runs-on: ubuntu-latest
    needs: enqueue
    steps:
      - name: Check out the code
        uses: actions/checkout@v3

      - name: Process Merge Queue
        run: |
          QUEUE=$(cat .github/merge-queue.txt)
          if [[ "$QUEUE" != "" ]]; then
            FIRST_PR=$(head -n 1 .github/merge-queue.txt)
            echo "Processing PR #$FIRST_PR"
            git fetch origin pull/$FIRST_PR/head:pr-$FIRST_PR
            git checkout main
            git merge --no-ff pr-$FIRST_PR
            git push origin main
            sed -i '' 1d .github/merge-queue.txt
          else
            echo "No PRs in the queue."

Explanation:

• on: pull_request: This triggers the workflow when a PR is labeled, opened, or updated.
• enqueue job: Verifies if the PR has the required label (e.g., ready-to-merge) and adds it to the queue if all conditions are met.
• process-queue job: Processes the queue by merging the PR at the front of the queue into the main branch.

Step 2: Label Your PRs

To trigger the merge queue, you'll need to label PRs as "ready-to-merge." This label signals that the PR has passed all necessary checks and is ready for merging.

You can manually add this label to your PRs or automate the process using GitHub Actions or bots. For example, you can create a workflow that automatically labels PRs as "ready-to-merge" when certain conditions are met (e.g., all checks are successful, or approvals are given).

Step 3: Monitor the Queue

Once you have set up your merge queue, you need to monitor the progress of PRs in the queue. The queue is stored in a .github/merge-queue.txt file, and the workflow will read this file to determine which PRs should be processed next.

Each time a PR is successfully merged, it is removed from the queue. It’s important to regularly monitor the queue to ensure that it doesn't become too long or cause delays in merging.

Advanced Configuration for Merge Queues

For more complex setups, you can:

• Use a GitHub App: Consider using GitHub Apps like Mergify that offer advanced merge queue management.
• Parallel Queues: Set up separate queues for different branches (e.g., staging and production).
• Custom Conditions: Use additional conditions like requiring a certain number of approvals before adding a PR to the queue.

Best Practices for Managing Merge Queues

• Keep the Queue Short: Regularly monitor and clear the merge queue to avoid long waits for PRs.
• Automate Labeling: Use workflows to automatically label PRs as ready-to-merge based on criteria like passing tests or receiving approvals.
• Handle Edge Cases: Implement fallback mechanisms for failed merges, such as removing the PR from the queue and notifying the author.

Monitoring and Troubleshooting Merge Queues

• Track Queue State: Use GitHub Actions to log the state of the merge queue and provide feedback to your team.
• Automated Notifications: Set up notifications in Slack or via email to inform team members when their PR is queued or merged.
• Handle Merge Failures: Implement workflows that handle merge failures gracefully, allowing for easy retries or manual intervention.

Conclusion

Setting up merge queues in GitHub Actions is a powerful way to automate your CI/CD pipeline, reduce conflicts, and improve collaboration. By following the steps outlined in this guide, you can streamline the pull request merging process, enforce consistent quality standards, and ensure that your codebase remains stable and conflict-free. With the right configuration and best practices, merge queues can significantly enhance your team’s workflow and productivity.