---
title: Scheduling Freezes
description: Temporarily block merging during maintenance, release, or blackout windows.
---

## When to Use a Freeze

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)

## Creating a Scheduled Freeze

<Image src={scheduleFreezeScreen} alt="Scheduled Freezes" />

In the dashboard under Merge Protections → Freezes:
1. Click `Schedule a Freeze`

2. Define start / end, and the timezone they are expressed in

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

4. Add exclude conditions: a pull request that matches all of them is 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

<Image src={newScheduleFreezeScreen} alt="New Scheduled Freeze" />

While a freeze is active, the `Mergify Merge Protections` check stays pending
on every matching pull request, and its summary names the freeze holding it
back: waiting for that freeze to end, or, when the freeze has no end date,
waiting for someone to remove it. Pull requests matching the freeze's exclude
conditions are left alone (see [Allowing Exceptions](#allowing-exceptions)
below), as are pull requests that cannot be merged anyway: drafts, closed ones,
and conflicting ones.

When the [merge queue](/merge-queue) is enabled, the freeze is reported in that
check but does not change its conclusion. The queue holds the merge back until
the freeze ends.

## Manual Instant Freeze

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

## Allowing Exceptions

To let specific pull requests through a freeze, use exclude conditions. They
are combined with a logical AND: a pull request escapes the freeze only when it
matches all of them. Exclude conditions `label=hotfix` and `label=urgent` let
through pull requests carrying both labels, not those carrying only one.

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

## Managing Freezes with the CLI

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

### Listing Freezes

List all scheduled freezes for a repository:

```bash
mergify freeze list
```

Use `--json` to get machine-readable output:

```bash
mergify freeze list --json
```

### Creating a Freeze

Create a time-bounded freeze:

```bash
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:

```bash
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 exclude conditions (`-e`):

```bash
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.

### Updating a Freeze

Modify an existing freeze by its ID:

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

### Deleting a Freeze

Remove a freeze by its ID:

```bash
mergify freeze delete <freeze_id>
```

:::note
  If the freeze is currently active, you must provide a reason:
  ```bash
  mergify freeze delete <freeze_id> --reason "Incident resolved"
  ```
:::