Scheduling Freezes

Use freezes to coordinate:

• Critical release stabilization
• High-traffic events where deploy risk must be minimized
• End-of-quarter / audit windows
• Incident response (manual immediate freeze)

In the dashboard under Merge Protections → Freezes:

1. Click Schedule a Freeze

2. Define start / end (UTC)

3. Add matching conditions: by default the freeze applies to every pull request, but you can limit its scope with this field

4. Add exclusion conditions: pull requests matching these conditions are allowed through the freeze, so specific pull requests (like hotfixes) can still merge while everything else is blocked

5. Save; active freezes appear in the list

During a freeze, the protection check fails with a clear message unless the pull request matches the freeze’s exclusion conditions (see Allowing Exceptions below).

Use the Freeze Merges Now action for immediate blocking. You can later unfreeze manually.

To let specific pull requests through a freeze, use exclusion conditions. Any pull request matching an exclusion condition is not blocked by the freeze.

Set exclusion conditions when you create or edit a freeze, either in the dashboard or from the CLI with the -e flag (see Creating a Freeze below). For example, exclude pull requests labeled hotfix so urgent fixes can still merge during the freeze.

You can also manage freezes from the command line with the Mergify CLI. The examples below cover the common workflows; the freeze CLI reference lists every command, flag, and option.

List all scheduled freezes for a repository:

mergify freeze list

Use --json to get machine-readable output:

mergify freeze list --json

Create a time-bounded freeze:

mergify freeze create \
  --reason "Release stabilization" \
  --timezone UTC \
  --start 2024-01-15T18:00:00 \
  --end 2024-01-15T22:00:00

Create an emergency freeze with no end time:

mergify freeze create \
  --reason "Incident response" \
  --timezone UTC

You can restrict which pull requests are affected with matching conditions (-c) and let specific ones through with exclusion conditions (-e):

mergify freeze create \
  --reason "Freeze main branch" \
  --timezone UTC \
  -c "base=main" \
  -e "label=hotfix"

Here the freeze applies to pull requests targeting main, except those labeled hotfix, which can still merge.

Modify an existing freeze by its ID:

mergify freeze update <freeze_id> \
  --end 2024-01-16T06:00:00

Remove a freeze by its ID:

mergify freeze delete <freeze_id>