With the Graphite merge queue, rather than being merged straight into main, the PR will enter a “queue” and wait its turn to be merged.

The merge queue is repository-specific. When you enable it for a repository, it will operate on its main/trunk branch. We currently don’t have support for multiple queues on a single repository (that is, two merge queues for the trunk branch and deploy branch of a repository).

​
Prerequisites

​
Enable the Graphite merge queue for your repository

Enable the Graphite merge queue for a given repository:

Go to Merge queue in the Graphite app settings page (https://app.graphite.dev/settings/merge-queue)

  1. Click Add merge queue

  2. Select the repository you want to enable it for by using the dropdown selector

  3. Click Next to adjust and save your merge queue settings

​
Configure the merge queue for your repository

In GitHub, most repos use either branch protection rules or rulesets to restrict certain actions. Follow the corresponding instructions for what your repo uses.

Some orgs may use both if transitioning from branch protection rules to rulesets: in that case, follow both instructions.

​
Branch protection rules

​
Push permissions

Some repositories restrict which accounts can merge to the trunk branch with the Restrict who can push to matching branches branch protection rule.

  • Required: if this setting is already enabled for your repo’s trunk branch, add graphite-app to the list of actors with push access. Otherwise, this rule will prevent the merge queue from merging PRs.

  • Strongly recommended: enable this setting, and make graphite-app the only actor with push access. This helps your teammates remember to use the merge queue for merging.

Graphite is not “required” to be the controller of history on main—and combining Graphite merge queue merges and non-merge queue merges will function—but the experience is much worse. If there are merges made to main outside the merge queue, they will be detected and the merge queue will restart the merge (rebase on top of those changes and restart CI) that is currently active. This could lead to failures if a timeout is configured for the merge queue, and results in users constantly being pushed behind non-merge queue users.

To view this setting, go to Settings in GitHub for the repository you have the Graphite merge queue enabled for.

Next, go to the Branches settings under Code and automation.

Click the edit button on the branch the Graphite merge queue targets (the branch which all PRs are merged into).

Here you’ll find the Restrict who can push to matching branches setting.

GitHub automatically includes admins and maintainers as users who can bypass these rules and there currently isn’t a setting to disable this.

As it stands, admins and maintainers will still have the ability to bypass the merge queue despite having these settings enabled.

​
Bypass PR permissions

In order to implement speed improvements, the Graphite merge queue requires the Allow specified actors to bypass required pull requests permission. While you can use the merge queue with this setting disabled, enabling it will help our merge queue merge faster with merge queue optimizations.

Under Protect matching branches → Require a pull request before merging

  • Ensure that you have Allow specified actors to bypass required pull requests selected

  • Add the Graphite App (graphite-app) to the list of who can bypass required requests

​
Rulesets

Simply add the Graphite App to the Bypass list with Always allow.

Note that multiple rulesets can apply to a single repo or branch. Make sure to update this for all rulesets impacting your merge queue enabled repo and branch.

​
Optional: Adjust merge queue settings

When you enable the Graphite merge queue for your repository, there are a few settings and configurations that are available to customize. Before you enable these settings, make sure you have GitHub App authentication enabled, and have configured your repository’s branch protection rules accordingly as explained above.

​
Default merge strategy

  • Rebase: rebase your changes on top of your trunk with commits unchanged (equivalent to GitHub’s rebase and merge)

  • Squash: rebase your changes on top of your trunk with each PR squashed to a single commit (equivalent to GitHub’s squash and merge)

If you haven’t enabled the queue, you can change the merge strategy for your PR directly from the merge modal. When the queue is enabled, you can set the merge strategy at the queue level so that all the PRs that are queued to that merge queue abide by the same rule.

​
Timeout

Configuring the merge queue timeout allows you to place an upper-limit on the amount of time a PR can stay at the head of the queue, ensuring that the queue never hangs in the event that a regression is introduced.

​
Adding to the queue via label

Specifying a merge label lets users add that label to a PR to let the merge queue know to merge it when it’s ready. Removing a label will remove it from the queue. This allows seamlessly merging PR’s from GitHub by just adding a label.

Adding a label to a PR that isn’t yet mergeable will toggle a PR’s Merge when ready property—as long as the label is applied, a PR will be merged when all branch protection rules are met.

You can automatically create this label in Graphite while adding a merge queue to your repo, or when modifying its settings.

You can only enqueue via label if you have a Graphite account set up.

If a user tries to add the merge queue label to their PR and doesn’t have a Graphite account, the label will be removed and the user will be prompted to create an account on Graphite in the PR’s comments on GitHub.