Deploying your Merge Queue

Smoothly transition to Mergify while optimizing the merge queue and potentially moving to Mergify exclusive merges.

Deploying and transitioning to Mergify’s Merge Queue involves two potential phases, each corresponding to different organizational preferences and maturity with the tool:

  1. Hybrid Phase: This phase allows for a mix, where manual merges and Mergify coexist, aiding teams in the transitional period. This approach does not disrupt existing workflows drastically and lets teams gradually adapt to the automated merge queue.

  2. Exclusive Mergify Merge Phase: In this phase, organizations can choose to enforce that only Mergify merges the pull requests, leveraging GitHub Branch Protection settings. This ensures a more streamlined, organized, and automated approach to merging.

None of those phases are mandatory, and they are defined here mostly as guidelines to inspire what your deployment scenario could be, and what your final workflow could look like.

Phase 1: Hybrid Phase — Coexisting Manual and Mergify Merges

Section titled Phase 1: Hybrid Phase — Coexisting Manual and Mergify Merges

Understanding the Hybrid Approach

Section titled Understanding the Hybrid Approach

In the hybrid phase, while the automated queue is in place, developers can still merge manually as usual. This flexibility is especially useful when transitioning gradually, ensuring minimal disruption to existing workflows.

  • Queue Disruption: Manual merges might interrupt the flow of the automated merge queue, making the process less optimal.

  • Extra CI Time: When manual merges bypass the queue, it might reset the jobs scheduled in Mergify, resulting in additional CI time and resource usage.

  1. Educate the Team: Brief the team on the new Mergify queue system and its benefits, encouraging them to prioritize the queue over manual merges.

  2. Monitor Usage: Regularly check how often the queue is being bypassed and encourage more use of Mergify for merging. You can monitor usage by checking who merged a pull request and notify someone when the queue is bypassed using an automation rule:

    - name: notify on manual merge
    - merged-by!=mergify[bot]
    # replace <your-username> by your GitHub login
    message: Hey @<your-username>, this PR has been merged manually.
  3. Gather Feedback: Understand any resistance or issues the team is facing with using the Mergify queue and address them promptly.

Phase 2: Exclusive Mergify Merge Phase

Section titled Phase 2: Exclusive Mergify Merge Phase

Once the team is comfortable with Mergify, you can choose to enforce Mergify exclusively for merging pull requests through GitHub Branch Protection settings.

Steps to Enforce Exclusive Mergify Merges

Section titled Steps to Enforce Exclusive Mergify Merges
  1. Go to Repository Settings: Navigate to Settings in your repository and locate the Branches section.

    Showing branch protections settings in GitHub
  2. Create/Add a Branch Protection Rule: Click on Add rule and configure the rule for the branch you wish to protect, typically main or master.

  3. Configure Status Checks: Under the rule, enable Restrict who can push to match branches and add Mergify as the authorized user.

    Showing adding rule popup on GitHub
  4. Save Changes: After configuring, click Create or Save changes.

Handling the Improbable: What to Do in the Event of a Mergify Outage

Section titled Handling the Improbable: What to Do in the Event of a Mergify Outage

At Mergify, our mission is to ensure consistent and uninterrupted service to aid your development processes. While we pride ourselves on our robust and resilient infrastructure, we also believe in transparency and preparation.

While the scenario painted here is improbable and not one we foresee, it’s always wise to be prepared. Rest assured, with Mergify, even in the rarest of circumstances, your workflow remains in your control. Our commitment is not just to provide an exceptional service but also to ensure you’re equipped for every eventuality.

Let’s address the elephant in the room: though it’s a scenario we’ve worked hard to avoid and has never occurred, an outage, however brief, remains within the realm of possibilities. In the unlikely event of such an interruption, it’s essential to understand that your development and deployment will not come to a halt.


  • Manual merges are always an option: Even if Mergify is momentarily unreachable, you can merge your pull requests manually. This ensures that your workflow remains uninterrupted.

  • Admin privileges remain supreme: In instances where Mergify is the only authorized application to merge, administrators can still override branch protection settings and enforce a merge. Your admin privileges grant you the autonomy to take the necessary actions.

  • Branch protection flexibility: If needed, branch protection can be temporarily disabled, allowing your engineering team to merge pull requests manually and bypass the merge queue. This is a contingency to ensure your operations don’t stall, even for a moment.

Transitioning to Mergify can be a smooth process, whether you choose to operate in a hybrid mode initially or move directly to exclusive Mergify merges. By configuring appropriately and addressing the team’s needs and concerns during the transition, you can ensure a more efficient, orderly, and automated development workflow.

Remember, the transition to Mergify is not just about enforcing new tools but about optimizing workflows and fostering a collaborative and efficient development environment. Take the time to educate, adapt, and make the most out of Mergify’s capabilities!