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 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)
Click Add merge queue
Select the repository you want to enable it for by using the dropdown selector
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-appto 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-appthe only actor with push access. This helps your teammates remember to use the merge queue for merging.
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.
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.
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.
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 optimizations like fast-forward merges.
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.
Fast-forward merge
We recommend keeping "fast-forward merge" enabled in order to process stacked PRs in parallel (a Graphite-only setting). You have the option to disable this if you prefer to not have fast-forward merges.
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.
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.
