Using the Graphite Merge Queue
The Graphite Merge Queue is repository-specific. When you enable the merge queue for a repository, it will operate on its main/trunk branch. We currently don't have support for multiple queues on a single repository (i.e. two merge queues for the trunk branch and deploy branch of a repository).
Enabling the merge queue for your repository
You can enable the merge queue for a given repository by doing the following:
Head to the repository settings page on the Graphite dashboard (https://app.graphite.dev/settings/repo)
Select the repository you want to enable merge queue for using the dropdown selector
Toggle the switch for merge queue on
Note
If you can’t access this page and you've contacted us to confirm your enrollment in the Graphite Merge Queue paid beta, we may not have added your org to our merge queue feature flag. Let us know on Slack, or reach out at hello@graphite.dev.
Tweaking merge queue settings
After merge queue is enabled for your repository, there are a few different settings and configurations that are available to customize.
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)
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.
[Coming soon] Optimistics
In optimistic mode, the MQ will process a configurable number of entries at the same time. The order of the entries will still be maintained.
Entries later in the queue assume earlier entries will be successful and begin processing rebased on top of them.
Each entry in the MQ will still require CI to pass before merging, but in optimistic mode, the CI of several entries can be processed in parallel.
[Coming soon] Batching
In batch mode, the MQ will process a configurable number of entries at the same time. The order of the entries will still be maintained.
In batch mode, only a single CI will be run on the group of entries being processed together.
In the initial release, if the CI fails, all entries will be marked as a failure and removed from the MQ.
In future releases, the MQ will be configurable to perform additional CI runs in the event of a failure to find the entry that introduced the failure.
The primary benefit of batch mode is to reduce CI costs by reducing the required number of CI runs in most cases.
Adding a pull request to the merge queue
Once merge queue is enabled on a repository, you'll still see the option to merge a pull request, but the confirmation modal will show an option to queue the PR rather than to merge it immediately. There are a few minor differences between the merge modal and the queue modal:
You cannot override the merge strategy from the queue modal as you can from the merge modal. Merge strategy for the queue is set at the repo-level through your repository settings
We don't support commit message/title edits from the queue modal as we do in the merge modal. For PRs merged using the squash & merge method, the PR title and PR description will be used for the commit message/title.
When queuing individual PRs (not a stack), you have the option to queue the PR as a hot-fix. When you queue a PR as a hot-fix, your PR will automatically jump to the front of the queue. Note that it will still wait to rebase and rerun CI, but will merge next in line. Hot-fixes will be marked in the Merge Activity page with a small flame icon.
Understanding the Merge Activity page
The Merge Activity page shows merge history for a given repo - you can select which repository you're viewing via the repo selector in the top right part of the page.
Queued PRs will be shown directly above the trunk's merge history - here you can see the PR's position in the queue, the size of the PR, and the estimated time to merge. Under the ... menu, you also have the option to remove PRs (including the currently merging PR) from the queue.
The timeline on the right side of the page shows the queue activity - this includes, merges, hot-fixes, removals, and failures.
In case you need to do so, you can pause the queue by clicking the ... on the PR header and selecting pause queue. When the queue is paused, PRs can still be added to the queue but they will not be merged.