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)
Select the repository you want to enable it for using the dropdown selector
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.
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)
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.
Fast forward merge
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).
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.
Configure the Graphite App's permissions
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 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
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.
