MergeQueue Documentation


Explore our guides and examples to integrate MergeQueue with your Github


Using MergeQueue several fast-growing engineering teams have reduced their time to production, while improving developer productivity.

With MergeQueue, your engineering team can save more than 5 hours a week per developer! Get started today with a free trial, and be up and running in under 3 minutes.


Getting Started

Introduction

MergeQueue is a FIFO (First-In-First-Out) queue that manages the merge workflow for your Github repository. The MergeQueue bot (MQ bot) uses Github Labels to identify PullRequests (PRs) that are ready to be merged and queues them up. The MQ bot then pulls the latest base branch for each of those PRs sequentially, runs and verifies the required status checks, and then merges the changes.


Quick setup

  1. Create an account. Register here.
  2. Follow the onboarding to connect to the MergeQueue Github app, authorize one or more repositories that you want to automate.
  3. Select the repository on the Repositories page to configure the rules
  4. Add the trigger label on Merge Rules page. This label identifies a PR ready to be queued.
  5. Verify the required status checks are set correctly on the Status Checks page.
  6. When a PR is ready, tag a PR with the trigger label defined above. Let the MergeQueue bot (MQ bot) handle the rest.

Automatic dequeuing

In case of failures, the MQ bot will remove the PRs from the queue, notify the owner and move on to the next one. The bot will also label the PR with the Github Label specified on the Merge Rules page as “On failure to merge, add label”. The default label is “blocked”. For all possible failure reasons, see the Failure reasons section of this documentation.

The bot will note remove the trigger label from the PR. It will only add the blocked label to it.


Automatic requeuing

If the PR is failed due to Merge Conflict or failing CI checks, the MQ bot actively monitors the state of the PR. When the merge conflict is resolved, or the CI checks are retriggered, the MQ bot will automatically remove the blocked label and requeue the PR. To avoid automatic requeuing, you can remove the trigger label.


Manual dequeuing

To dequeue a queued PR, simply remove the trigger label. The PR will be removed from the queue.


Skip the line

There may be scenarios where something needs to be urgently merged and the queue is backed up. The skip-the-line feature lets you skip ahead of the queue and merge first. This can be specified as an additional label in the configuration for “Label for skipping the line”. So if a PR is tagged with the skip-the-line label, it will get promoted directly to the top.

In case more than one PR is tagged with the skip-the-line label, they will get merged in the order of being tagged.


 

Merge Rules

Merge rules are the core of how MergeQueue bot behaves. MergeQueue primarily relies on Github Labels to communicate with the PullRequests. There are several configurations that you can set up here. Below is the explanation of each of those settings.

Triggers

Label for trigger

This label is used to identify that a PullRequest is ready to be processed by MergeQueue bot. Once labeled, the bot will verify that the PR has all the required conditions true and then merge the PR.


Merge Preconditions

Number of approvals

Minimum number of reviewers that should approve the PullRequest before it can qualify to be merged. Defaults to 1.

Required approvers

List of github handles of the reviewers whose reviews are required. Default is empty.


Merging

Base branch to merge the PRs into

MergeQueue will only monitor PRs merging into this base branch. Defaults to master branch.

Merge HEAD base branch into current branch

Whether you want MergeQueue to merge the latest base branch into the current branch of PullRequest before verifying the CI statuses. Defaults to ON.

Default merge strategy

How do you want MergeQueue to merge the PR. You can choose between:

  • Squash and merge
  • Create a merge commit
  • Rebase and merge
Defaults to squash and merge.

Merge overrides

You can specify overrides to the above merge strategy using Github Labels. When a PR is flagged with this label along with the trigger label, MergeQueue will merge the PR using this strategy instead of the default strategy. Leave empty for no overrides.


Miscellaneous

On failure to merge, add label

If the MergeQueue bot failed to merge a PR, have the bot flag the Pull Request with this label. Generally helpful to identify that the PR has failed to merge. MergeQueue also removes the trigger label when the PR fails to merge.


 

Status Checks

MergeQueue automatically captures all the status checks from your repository. To review the status checks you can go to the Status Checks page. You can also manually trigger a refetch to extract the latest status checks from the Status Checks page.

On this page, you can select the status checks that the MQ bot will validate before merging the PR. The MQ bot validates these rules while merging changes in both restricted and non-restricted branches. For example, in cases where you use MQ bot to merge changes to a non-restricted branch, you can still let the bot verify the status checks before merging.

Please note, for the MQ bot to be able to merge changes in a restricted branch, all required status checks must be selected on the Status Checks page. The bot might otherwise fail to merge the changes.


 

Managing team access

MergeQueue offers multi-user account capabilities in all plans. You can invite all your team members to access the MergeQueue dashboard. There is no additional cost associated with inviting your team members to use the MergeQueue dashboard. See Billing section to understand how pricing works.

To invite your team members to access MergeQueue dashboard, go to Users and Roles page, and where you can enter their email address and choose appropriate role.


Users and Roles

There are two different roles you can find in User and Roles section.

  • ADMIN: The admin has access to the entire MergeQueue product including the ability to add more users and manage billing.
  • MEMBER: A member is only allowed to view the dashboard and the queue. The members are not allowed to invite others or revoke someone’s access. Members also cannot view or update billing information.


Google SSO

MergeQueue also offers capability for users to login using Google SSO. Additionally, you may whitelist your entire company domain to access your MergeQueue account without having to invite each of them individually. To do so, scroll to the bottom of the Users and Roles page, and activate the setting:

Allow all users with email domain: <yourdomain> to automatically login to this account.
Please note that this capability to whitlist domain is only available in the pro plan.


Okta authentication

MergeQueue also offers SAML based Okta authentication. We only offer SAML authentication in our enterprise plans, please contact support@mergequeue.com for more information and configuration guide.


 

Analytics

Analytics offers insights into the performance of MergeQueue and provides metrics on its usage. This capability is only available in the Pro plan. Following metrics are offered on the Analytics page of MergeQueue.


Time in Queue (mins)

The time a PR spends in the queue before it is merged by the MQ bot. The time is measured starting when the PR is queued (not labeled). This only includes the PRs that were merged by the MQ bot. The metric is reported as: Average, p50 (50th percentile), p75 (75th percentile), p90 (90th percentile) and p100 (100th percentile).

MergeQueue bot usage

Represents how many PRs were merged by the bot v/s merged manually segmented by day.

PR failure reasons

Gives you a better understanding of how many PRs are failing to automatically merge and why. The breakdown is done by Failure reasons. You can find the details about all the reasons in the Failure reasons section of this documentation.

The failed PR is counted multiple times if it failed multiple times in its lifecycle.

PR sync frequency

This metric captures how many times the bot pulls the latest base branch into the current PR. This should only happen at most once if everyone uses the MQ bot for merging the PRs.


 

Timeline

Timeline is a great tool for you to look at all the current and past actions taken by the MQ bot. This capability is only available in the Pro plan. Within the Timeline page, you can also filter the activities based on type.

ActionDescription
OPENEDThe moment when the PR is opened by a developer. This is the official creation time for a PullRequest.
LABELEDWhen the PR is labeled by a developer. If a PR was unlabeled and labeled again, this would be reported more than once for the same PR.
UNLABELEDWhen the PR was manually unlabeled by a developer. This may also be represented multiple times if the PR was unlabeled multiple times. Unlabeling also automatically removes the PR from the queue.
QUEUEDThis is the time when a PR is queued by the MQ bot. Typically this would be same as the time when the PR was labeled, but in the case where the PR was labeled before approval, the MQ bot will wait for proper approvals before queuing the PR.
TOPThis is the moment when a PR reaches the top of the queue. At this point, the MQ bot will be actively processing the PR. It’s possible for a PR to lose the top position when someone uses the Skip-the-line label in another PR.
MERGEDWhen the MQ bot merged the PR. This will not capture any merges that were done manually without the MQ bot.
BLOCKEDA PR may get flagged as blocked if it failed to merge. See failure reasons section for all scenarios where a PR may be flagged as blocked. In all such cases, the PR is dequeued and the MQ bot moves on to the next PR in the queue.

 

Failure reasons

MergeQueue bot flags a PR as blocked and adds the label specified on the Merge Rules page. The failure reasons are also reported on the Blocked PRs page in MergeQueue dashboard and also reported in the PR comments if commenting is enabled.

ReasonDescription
NOT_APPROVEDa PR does not have the required number of approvals. Typically a PR should not get queued if the required number of approvals don’t exist, but you can still see this error if a reviewer has changed their review status in a subsequent review comment.
READY_LABEL_REMOVEDSomeone has removed the trigger label to dequeue the PR, it will be flagged.
BLOCKED_LABEL_MANUALSomeone has manually added the failure label to block the PR.
MERGE_CONFLICTThere’s a merge conflict to merge the PR.
FAILED_TESTSOne or more of the required CI status checks failed.
MISSING_OWNER_REVIEWThe PR does not have required checks form the codeowners.
BLOCKED_BY_GITHUBGithub blocked the merge of PR for any reason.
CI_TIMEDOUTOnly reported if a CI timeout is specified in the merge rules. A PR would be dequeued with this status if the required CI status check did not complete in specified time.
FAILED_UNKNOWNFailed due to an internal error.

 

Comments in PR

PR commenting is enabled by default. This can be disabled from the Merge Rules page if needed. Comments are a great way to stay on top of the activity of the MQ bot. Following comments are generating when this feature is enabled

  • Waiting for approval before queuing - If the PR is labeled before approval. This flags that the PR will be queued after the required approvals are complete.
  • PR is on top of the queue now - This is the moment when a PR reaches the top of the queue. At this point, the MQ bot will be actively processing the PR. It’s possible for a PR to lose the top position when someone uses the Skip-the-line label in another PR.
  • The CI is taking too long, the queue is waiting - This is only applicable to Batch mode. It can happen if draft PR CI is completed but the original PR is still pending CI status.
  • PR queued successfully. Your position in queue is: <number> - Reports successful queuing giving the current position of the PR in the queue.
  • PR failed to merge with reason: <reason> - Reports a PR getting dequeued with one of the reasons as described above.

 

New features

Batch mode

If you think sequential merging may not work for your use case, you can try our new Batch mode. We designed Batch with high output teams in mind where the sequential continuous integration cycles may cause long wait cycles. This feature is only available in Pro plan.

Batch Mode requires good understanding of several principles, as things work somewhat differently in batch mode. To enable batch mode, you can find a toggle option on the Merge Rules page. You can find the complete details about Batch mode on our blog we wrote recently.


Rebase

MergeQueue also provides the capability to use Rebase instead of creating a merge commit while pulling the base branch into your PR. This capability is still in beta, please contact support@mergequeue.com to get access to this feature.


Webhooks

Webhooks are a great way to manage your flaky tests. If you have some CIs that are flaky, you can use webhooks to retrigger those CIs without losing the position in the queue. The webhooks are built in a generic way where you can specify any headers and body to make an API request. Additionally, you can specify the retry attempts before declaring a CI as failed. This feature is still in beta, if you need assistance with the setup, please contact support@mergequeue.com.


 

Billing

Do I need a credit card to sign up for the trial?

No, the trials do not require any payment method. You can use the product risk free for the first 30 days. We will only start charging you after 30 days, so whenever you are satisfied with MergeQueue, you can go to the billing section and add your credit card.

How do I know how much I will be charged?

We charge based on the number of active collaborators in your repository. Active collaborators are defined as the collaborators who have created a Pull Request and have used MergeQueue on their PR. You can review the count of Billed users in the Collaborators section of MergeQueue.

How do I cancel my plan?

You can send us an email to support@mergequeue.com to cancel your plan any time.


 

Slack notifications

Using Slack app integration, you can receive notifications about the queue events. Currently supported Slack events are queued, merged and failed.


 

Troubleshooting

I have labeled the PR but it’s not merging.

There could be several reasons why the bot is not merging your PR.

  • Check from your Dashboard whether the queue is active or paused. If the queue is paused it will not pick up any changes.
  • Check whether all your CI statuses are completed (no required status is still pending).
  • Check whether there is no other PR ahead of your PR that is pending merge.
  • Go to the Github app page and verify that the app is still authorized to your repository. If not, you may need to reconnect the app.

Once you have verified the above status, open your web app, and look at the Open and Blocked Queue. If it is in Blocked Queue, there should be a reason listed for blocking as well. If none of these steps help, please contact us support@mergequeue.com

My account is blocked, how do I unblock it?

If you are still on a trial plan and have not entered billing information, your account will automatically be suspended after 30 days. Your account may also get blocked due to a failed payment. Once you update your billing information, your account will get unblocked.