Merging a stack of PRs manually through GitHub can be time-consuming and involve a lot of context switching. You merge, rebase, wait for CI to pass, and merge again all the way up the stack—or you're forced to ditch the clean PRs you've carefully created, squashing your changes back into a single mega-PR for the sake of merge speed.

Graphite offers an automated solution that gives you the best of both worlds.

Once your PR is approved and passes CI (and any other checks or merge protections you've enabled in GitHub), you can merge it from Graphite. Just click the purple "Merge" button on the right side of the PR title bar.

Merge a stack of PRs

Depending on which PR you are viewing in the stack, this button will behave differently:

• If you're on the first PR in the stack or are merging a stack of one, the Merge button will just merge that single PR.

• If you're in the middle of a stack, Merge N where N is your position in the stack and will merge all PRs up until the Nth.

• If you're at the top of the stack, all PRs in the stack will be merged.

Merge (N) PRs lets you fire-and-forget merging your stack. When you click the button, Graphite automatically merges each of your PRs one-by-one.

This feature rebases PRs on an as-needed basis (to avoid merge conflicts generated by GitHub's lack of stack support). And it waits for GitHub checks to pass at each step of the way before merging.

Configure merge options

Clicking merge will first present you with a modal to configure your merge options before starting the merge job. In this merge modal, you have the option to:

• Select your preferred merge strategy. Graphite pre-fills with your default merge strategy from GitHub.

• Edit a custom commit title and message for your PR. Graphite will use your PR title and message as the commit title and message by default.

• Use your GitHub admin merge privileges to merge past blockers, if applicable. (Please note that admin merge is available only in repositories that do not use rulesets.)

A confirmation appears in the bottom left corner of the screen once your PR is merged.

Track the status of your merge on GitHub

Graphite will update a single comment on GitHub with the status of your PR's merge.

Compatibility with GitHub branch protection rules

If you have the dismiss stale pull request approvals when new commits are pushed branch protection rule enabled for your repository on GitHub, you will not be able to successfully merge a stack with the Graphite UI.

Resolve merge conflicts

If Merge (N) fails due to a rebase conflict, go to your terminal and run gt sync && gt restack && gt submit --stack (resolving any conflicts along the way and running gt continue). Once you've done this, go back to the affected PR in Graphite (or to the same place in the stack where you initially kicked off the Merge (N) job), and click Merge (N) one more time to re-queue the PR for merging.

Types of merge conflicts stack merge can resolve

When PRs are merged on GitHub using a squash and merge or a rebase and merge, GitHub creates a commit/set of commits for those merged changes.

This means that if you have a stack with PR A at the base, followed by PR B and PR C, when PR A is merged into trunk:

• GitHub creates a commit or set of commits on trunk for the changes in PR A.

• Critically, because this is a new commit, the common ancestor of PR B and trunk does not change.

• As a result, GitHub thinks PR B now includes the commits of both PR B and the already-merged commits of PR A.

This behavior becomes problematic when you have a PR A and PR B that modify the same lines and you merge both PRs using one of the aforementioned merge strategies. For any PR C that is stacked atop PR A and B, the following transpires:

• The latest version of the change lines on trunk are those in PR B.

• GitHub believes that PR C contains the commits in PR A and PR B.

• When GitHub tests mergeability of PR C, it first tries to apply PR A—and now gets a merge conflict—even though in reality you're simply replaying history and there's no new change.

If you use the Graphite CLI, you'll notice that the CLI handles this scenario for you intelligently. When GitHub reports these sorts of merge conflicts, a gt sync will pull down the latest changes and rebase PR C for you, cutting out the problematic commits—and a subsequent re-submit will then eliminate the detected merge conflict for PR C.

Merge (N) is designed to similarly automatically resolve this type of merge conflict without the need for manual intervention or monitoring. When a merge conflict is found, the merge cron performs a shallow clone of the repository, containing just the stack commits and the trunk commit and utilizes Graphite's knowledge of the stack to perform the same set of operations.

How a stack merge works

Each time the cron job processes a merge job it runs through the following decision tree:

• If the base PR in the stack has pending GitHub checks, do nothing.

• If the base PR in the stack is passing all GitHub checks and can be merged, merge. The next PR in the stack is now the new base PR.

• If the base PR in the stack has merge conflicts, rebase the PR and re-submit it (re-entering the waiting-for-CI phase).

During the merge process, Graphite prioritizes:

1. Speed of overall stack merge.

2. Minimizing the number of total CI runs.

To achieve these principles, it's important to note that:

• Graphite merges rather than rebasing each individual PR before merging.

• Graphite only rebases PRs lazily. When Graphite detects a merge conflict on a PR, Graphite only rebases that PR, and not the additional PRs further up the stack. This means that if a stack has m merge conflicts, there will only be m total rebases (and additional CI runs) kicked off by the merge process.

Merge job duration

Graphite's cron job to process outstanding merge jobs runs at a cadence of once per minute.

As a result, the length of a merge job depends on how many PRs need to be rebased. If there are no merge conflicts, Merge (N) will take n minutes, but if there are merge conflicts, job time is a byproduct of the time it takes to run GitHub checks on a PR and how many PRs encounter merge conflicts.

Compatibility with third-party merge queues

Today, merge stack supports label-based merge queues, with future plans to support GitHub's merge queue (currently not compatible).

If you're not sure whether Merge (N) will work with your team's merge process, feel free to reach out to support@graphite.dev—we'd love to help you with this.

Automatic rebasing

Requirements

Graphite will automatically rebase your partially-merged stacks so long as you click merge from the Graphite app. This feature does not work when merging from GitHub.

How it works

When you partially merge a stack of pull requests, Graphite runs a job that automatically rebases the remote branches corresponding to the PRs “upstack” of the one(s) you merged. This means there is never a moment where the new base of the stack points to a branch or pull request that no longer exists, so there’s no possibility of seeing an incorrect code diff.

This operation results in temporary graphite-base/* branches that lets Graphite retarget the rebased branches atomically -- ensuring your CODEOWNERS rules and GitHub Actions workflows don't misfire.

Ignoring Graphite's temporary branches in your CI

You should configure your CI to ignore branches with named graphite-base/* . Not doing so can result in unnecessary builds for these temporary branches and cancelled jobs when Graphite deletes these branches.

Here's how to disable running CI for these branches in GitHub Actions:

on:
  pull_request:
    types: [opened, reopened, synchronize]
    branches-ignore:
      - '**/graphite-base/**'