How to manage dependent PRs with Depends-On

There are a few ways to express the same ordering, and they do not cost the same thing.

Pick the header when the pull requests are genuinely separate changes that happen to have an order, which is most of the time, and especially when they live in different repositories. Pick a stack when one change was split into commits that only make sense read in sequence.

Add a Depends-On: line to the body of the pull request that has to wait. One line per dependency, anywhere in the description:

Adds the billing API client to the web app.

Depends-On: #142
Depends-On: myorg/billing-service#87
Depends-On: https://github.com/myorg/schemas/pull/9

That pull request now merges only after #142, #87 in billing-service, and #9 in schemas have all merged. Everything else about it stays the same. Reviewers review, CI runs, and the pull request can sit in the queue. The one step Mergify withholds is the merge, and it reports why on the pull request itself, so the next person to look at it does not have to reconstruct the reason.

Three reference formats work, and you can mix them in the same body:

• #123 for a pull request in the same repository.
• org/repo#123 for a pull request in another repository.
• https://github.com/org/repo/pull/123, which is what you get from copying the address bar.

Two limits are worth knowing before you rely on this. Circular chains and self-references are ignored rather than reported, so a pull request that depends on itself simply merges. And a dependency between pull requests targeting different branches is not re-evaluated automatically, so if the blocked pull request stays blocked after its dependency merges, comment @mergifyio refresh on it.

Same header, wider reference. This is the case a stack cannot cover, since a stack is a chain of branches inside one repository, and it is the case teams hit hardest: the schema and its consumer, or the shared library and everything that pins it.

Two conditions apply. Every referenced repository must have Mergify installed, and it must belong to the same GitHub organization. Mergify is watching those pull requests through the same installation, which is how it knows when they merge.

You can combine the dependency with a date when a change is ready but should not ship yet. Both headers live in the same body, and the pull request waits for both:

Depends-On: myorg/billing-service#87
Merge-After: 2026-09-01T09:00:00[Europe/Paris]

Both headers are built in, and neither needs a line of configuration. The people who need them are rarely the people who own .mergify.yml.

A dependent pull request goes through the queue like any other. It is tested against the state the branch will have at merge time, and it is held at the merge step while its dependency is open. When the dependency lands, it stops being held.

Turn on auto-merge and the header becomes the only brake you need. This configuration queues anything with an approval and green CI, and the dependent pull requests still wait their turn:

merge_protections_settings:
  auto_merge_conditions: true

merge_protections:
  - name: review-and-ci
    if:
      - base = main
    success_conditions:
      - "#approved-reviews-by >= 1"
      - check-success = ci

Nothing in it mentions dependencies, and nothing has to. Nobody edits a shared config file to declare that this week's migration goes before this week's query change.

The queue does read Depends-On for one specific shape. When pull requests are both chained by branch (each one based on the previous one's head) and carry the marker, the queue recognizes a stack and moves it as a unit: @mergifyio queue on the top pull request enqueues the whole chain, predecessors are validated ahead of successors, and if one fails, the successors still in the queue are dequeued instead of being tested against a dependency that just broke. Chained branches without the marker do not get that treatment. The queue handles them as unrelated pull requests.

When the dependency exists because you split one change into several reviewable commits, do not write the headers by hand. Any stacking tool does it for you, including GitHub's own gh stack and the open-source Mergify CLI: mergify stack push opens one pull request per commit, bases each on the previous one, and adds the Depends-On: #NNN marker between them, which is exactly the pair of signals the queue looks for.

mergify stack push

For a dependency that points outside the stack, put the Depends-On: line in the commit message body. It is copied into the pull request description on push, so it survives the next stack push instead of being overwritten.

Two limits on the stack side: chains deeper than 20 pull requests fall back to per-pull-request queueing, and a draft anywhere in the chain stops the queue from pulling the stack through. Mark it ready before you queue.

Depends-On is one of the built-in controls of the Mergify merge queue, next to Merge-After and the rules you write on labels, files, and authors. GitHub branch protection has no equivalent, which is why the ordering usually ends up as a label and a reminder.

It pays off most on top of a queue, since the queue is what tests each pull request against the state it will actually land on. If you do not have one yet, start with setting one up on GitHub, and read the merge queue guide for what the queue does to your branch. For holding a whole branch rather than one pull request, running a queue during a code freeze covers the other end of the same problem.