Set up the Graphite Merge Queue

Learn how to set up and configure the Graphite Merge Queue for your team.

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 merge queue for your repository

Enable the Graphite Merge Queue for a given repository:

Go to Repository settings in the Graphite app (https://app.graphite.dev/settings/repo)

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

  2. Toggle the On switch

Adjust Merge Queue settings

After 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.

  • 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)

You can change your merge strategy in the Repository settings. 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.

You can opt to enable "fast-forward merge" on either of the above strategies in order to process stacked PRs in parallel (a Graphite-only setting).

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.

You can enable a couple options (see the following sections for more info) in your Graphite Merge Queue settings with the proper GitHub permissions:

  • Enforce the Graphite Merge Queue for a repository

  • Enqueue via label

In order to enable these features, the Graphite App needs to be provided with some special permissions on the repository.

First, in GitHub go to settings 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).

Under Protect matching branchesRequire 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

Enforce the Graphite Merge Queue for your repository

Enforce use of the Merge Queue by restricting merge access to the trunk branch to only the graphite-app bot.


Note

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.


Go to your branch protection rules settings in GitHub, and enable restrict who can push to matching branches. Add the Graphite App (graphite-app) as the actor who can push to the branches.


Warning

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.


Enable adding to the queue via label

If you have collaborators that want to use the Graphite Merge Queue but review/merge primarily from the GitHub UI and not the Graphite UI, you can configure your merge queue such that adding a specific label to a PR (in GitHub or Graphite) will automatically add it to the queue, and removing a label will remove it from the queue.

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.


Note

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.


First, create a label on GitHub that you want to reserve for queueing purposes. You can do this by clicking the settings icon on the labels category of a pull request on GitHub.

Next, go to your Graphite repository settings and select your merge queue label under the add to merge queue via label setting.