Pausing the Merge Queue

Mergify’s Merge Queue offers a feature known as “pausing” that grants users increased control over the automation process during special circumstances. Let’s explore what pausing involves, its impacts, and its typical use cases.

When you pause the merge queues:

1. Pause All Queues: All active merge queues will be suspended, not just a specific one. This affects all queues in the project.

2. Addition to the Queue Continues: Even with paused merge queues, new pull requests can still join the queue. This ensures pull requests remain organized and ready for when operations resume.

3. Stops Scheduling and Actions: After pausing the merge queues, Mergify will not schedule new checks, update, or merge pull requests. Pull requests can enter the queue but won’t be acted upon.

4. Cancel Running Checks: As soon as the queues are paused, Mergify cancels any running checks and waits for the queues to be resumed.

Navigate to your Mergify dashboard. There you’ll find an option to pause the merge queues. Clicking on this will suspend all active queues.

You can also pause the merge queues programmatically using the Mergify API. For detailed steps on how to achieve this, refer to our API documentation.

The Merge Queue freeze API has been deprecated and will be removed on 31st March 2025. The feature that it provided is now covered by differents parts of Mergify, depending on your use case.

If you were using freeze for a partial freeze of a single queue rule (with or without cascading), you should now to rely on Merge Protections to avoid pull requests entering the merge queue entirely.

If you were freezing the entire merge queue, you can now leverage the Pause feature instead. It now exposes an extra argument allow_checks_to_run which define whether the checks should be doone in the queue while paused (default to false). To mimic the behaviour of the deprecated freeze API, set this parameter to true. In either case, nothing will be merged until the pause is removed from the repository. For more details about this endpoint, you can check out the API reference.

During a major incident with the Continuous Integration (CI) system, the pause feature can be invaluable. If there’s a likelihood that checks will fail and consequently eject the pull request from the queue, it’s beneficial to pause the merge queues.

If an incident is unrelated to the CI, like a production issue, but you wish to halt merging while allowing checks to run, then the freeze feature is a more suitable choice. “Freezing” simply halts merges, letting checks and other actions proceed.

1. Maintain Queue Integrity: During CI failures or other disruptions, pausing ensures pull requests stay in the queue, preserving their order.

2. Flexibility: It provides an immediate response tool during unexpected complications, giving you control over the merge process.

3. Reduce Noise: Constantly failing checks during a CI incident can create unnecessary notifications. Pausing the queue mitigates this.

The pause feature of the Mergify merge queue offers users an enhanced layer of control and adaptability during special situations. Familiarizing yourself with when and how to pause your merge queues can optimize your workflow and reduce disruptions.