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. How that reads on the check depends on the merge queue: with the queue enabled, the protection is reported as pending while the dependency is open; without it, an unmet Depends-On fails the check until every pull request it names has merged

• A dependency 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.

• At most 50 dependencies are resolved. A body declaring more leaves none of them resolved and fails the protection, with the check naming the count it read and the limit, until the body names fewer.

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. Every Mergify report on the pull request, including the Mergify Merge Protections check, lists the condition as Merge-After, with a note that the value in the pull request description is not a valid date and a link to this section. To unblock the pull request, change the value to a timestamp.

When the value contains a pull request reference (#123, org/repo#123 or a pull request URL), the report also points to Depends-On, the header that waits for another pull request to merge. Write that header with the reference alone, in one of the forms shown above: Mergify ignores a Depends-On line that holds anything else, and the pull request is then no longer held.

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.