View as Markdown

Built‑in Merge Protections

Protections available out of the box: Depends-On, Merge-After, Configuration Changed.

These protections are automatically interpreted, no configuration required.

Depends-On

Section titled Depends-On

Block merging until specified pull requests are merged.

Declare dependencies in the PR body:

Depends-On: #123
Depends-On: https://github.com/org/repo/pull/123
Depends-On: org/repo#123
Using Depends-On in the pull request body on GitHub

Rules:

  • All referenced PRs must be in repositories with Mergify enabled
  • They must belong to the same organization
  • Cycles are ignored (a PR depending on itself or circular chains)

Use cases:

  • Feature split across multiple repos
  • Schema then implementation
  • Chained refactors

Seeing dependencies in the merge queue

Section titled Seeing dependencies in the merge queue

Because a pull request with a Depends-On: header merges after the ones it depends on, it can sit behind a lower-priority pull request for no visible reason. The merge queue shows why: a queued pull request held back by a dependency carries a dependency icon in the list, and its side panel gains a Depends On section linking to each queued pull request it waits for. The merge queue status API reports the same list as depends_on_pull_requests.

This display covers dependencies inside a stack in the same repository. A dependency on a pull request in another repository still blocks the merge, but the queue does not show it.

Merge-After

Section titled Merge-After

Delay merging until a future time using a header in the PR description:

Merge-After: 2025-09-01T09:00:00Z

Supports the standard timestamp format. Useful for coordinated releases or off-peak deploy windows.

Using Merge-After in the pull request body on GitHub

Was this page helpful?

Edit this page on GitHub