Skip to main content

Documentation Index

Fetch the complete documentation index at: https://graphite-58cc94ce.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

If you already use a separate external merge queue offering, Graphite can integrate with that merge queue to reduce the manual work required to merge stacks of PRs.

​
GitHub merge queue

​
Enable the GitHub merge queue integration

Go to the Merge queue settings page:
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

5

Select Enable adding to GitHub merge queue and save your merge queue settings

​
Enqueue PRs in Graphite for the GitHub merge queue

To merge, click the Merge when ready toggle in the top right of the PR page. When a PR is the first open PR in the stack and has Merge when ready active, Graphite will then add the PR to your GitHub merge queue. Upstack PRs can have Merge when ready toggled so they will automatically merge once the downstack PRs have merged.
When merging a single PR at a time with the GitHub merge queue, you may notice that an upstack (not yet merged) PR shows files or commits that were actually introduced by a downstack PR that just merged. This is an expected side-effect: after GitHub merges a PR, it deletes the merged branch and auto-retargets dependent PRs to the base branch (e.g. main) without first rebasing.To mitigate this, after the downstack PR merges you can locally run gt sync && gt submit to rebase the upstack PRs’ branches.Note that if the upstack PRs have Merge when ready enabled from in Graphite prior to the downstack PR merging, they will automatically rebase after downstack PRs merge.

​
Other merge queues

If you use a merge queue outside of the Graphite’s or GitHub’s merge queues, then Graphite still can be configured to add PRs to your queue by applying a custom label per PR.
If your merge queue enqueues PRs for merging using another method, such as running CLI commands or calling an API, then Graphite won’t be able to integrate with it at this time.

​
Prerequisites

  1. Ensure that a PR can be enqueued via label
  2. (Recommended) Prevent the merge queue from merging into branches named graphite-base/*. See Automatic rebasing for more information.

​
Enable the external merge queue integration

Go to the Merge queue settings page:
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

​
Enqueue PRs in Graphite for the external 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 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.