Built⁠-⁠in Merge Protections

These protections are automatically interpreted, no configuration required.

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

Rules:

• All referenced pull requests must be in repositories with Mergify enabled. A reference Mergify cannot resolve (the repository has no Mergify, or the pull request does not exist) fails the protection rather than waiting on it

• They must belong to the same repository owner: the user or organization that owns the repository declaring the dependency

• A dependency that is still open blocks the protection until that pull request merges. One that was closed without being merged can never be satisfied, so it fails the protection the way an unresolvable reference does. Reopen it or drop the header. A circular chain (or a pull request that lists itself) never resolves, so every pull request in the loop stays blocked indefinitely, and none of them merge.

Use cases:

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

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.

The queue shows this only for the pull requests ahead of it in a stack in the same repository, and only while they are still queued: one that has merged or been dequeued leaves the list. Any other dependency still blocks the merge without appearing there, whether it points at a pull request in another repository or at one in the same repository that is not part of the same stack.

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

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

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

A value Mergify cannot read as a timestamp blocks the pull request indefinitely rather than failing the protection outright. The check reports Merge-After date is invalid alongside the value it read; fix the header in the pull request body to unblock it.

When a pull request targeting your default branch modifies your Mergify configuration file, Mergify validates the new configuration and reports the result as a Configuration changed check. This protection requires that check to succeed, so a pull request whose configuration Mergify cannot validate does not merge. A pull request that leaves the configuration file alone is not affected.

A pull request that deletes the configuration file rather than editing it never gets a Configuration changed check. It reports under Configuration has been deleted instead, which Mergify posts as a success, and that check satisfies this protection too. Removing the configuration is an accepted outcome, not a failure.