If you already use a separate external merge queue offering, Graphite's external merge queue integration simplifies the merging experience by:

• Enabling custom merge button behavior, overriding the default behavior, and

• Automatically merging and rebasing PRs one-by-one using that custom behavior

This offers a quick and seamless way to onboard your team to Graphite when you're already using an external merge queue.

Limitations

Today, this integration only supports merging by applying a label to the PR. If you merge PRs with your merge queue another way, such as running CLI commands or calling an API, Graphite won't be able to merge your PRs for you.

Unlike Graphite's merge queue, external merge queues don't use stack context to optimize merges, so you won't benefit from the same performance boosts and guarantees available with the Graphite merge queue.

Enable the external merge queue integration

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

1. Click Add merge queue

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

3. Select External merge queue integration as the merge queue type

4. Click Next to specify your merge label and save your merge queue settings

Merging via your merge queue

Once you've completed the configuration steps above, PRs created in that repo can now be merged via your merge queue.

• For single PRs, and base PRs in a stack: the merge button is replaced with an "Apply merge label" button that immediately applies the merge label

• For upstack PRs: the merge button is replaced with an "Apply merge label when ready" button that acts as follows: for a stack of PRs A ← B ← C, where A is the base PR:

  • A immediately receives your repo's merge label, handing off merging to your merge queue

  • When A is successfully merged, Graphite rebases B, and upon succeeding applies your repo's merge label. If the rebase fails, Graphite informs the author as usual.

  • It repeats the process for B, and so forth for larger stacks.

During the merge process, the PR status for each PR will communicate if the PR is actively waiting on downstack merges, or if the merge has been handed off to your merge queue.

(Optional) Updating your PR inbox

Enqueued PRs

To track enqueued PRs in your PR inbox, you can create a section with the following settings:

Blocked PRs

Many merge queues represent merge failures by adding a label denoting that the PR is blocked. You can create a section to track these with the following settings:

Troubleshooting

• PRs getting evicted while enqueued: once you mark as a stack as ready to merge, re-stacking those PRs when they're already in your merge queue may result in your merge queue evicting them due to making changes. You may want to avoid re-stacking a PR while your merge queue is processing it.

• Handling failed merges: your merge queue may take actions like adding a "blocked" label on PRs that failed to merge. To re-enqueue after fixing the issues, manually remove the custom label.