---
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` → `Scheduled Freezes`:
1. Click `Schedule a Freeze`

2. Fill in the reason at the top of the editor. It is required, and it names
   the freeze wherever Mergify reports it

3. Under `Schedule`, set `Starts` and `Ends`, and the `Timezone` they are read
   in. Leave `Ends` empty for a freeze that lasts until you remove it

4. Under `Scope`, add the [conditions](/configuration/conditions) a pull
   request must match to be blocked. Leave it empty to freeze every pull
   request on the repository

5. Under `Exceptions`, add the conditions that let a pull request through the
   freeze, so specific pull requests (like hotfixes) can still merge while
   everything else is blocked

6. Click `Save Freeze`; the freeze appears in the list under `Upcoming` until
   it starts

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

Without the merge queue, an active freeze leaves the `Mergify Merge
Protections` check 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 is not what decides its conclusion. The queue holds the merge back
until the freeze ends.

:::caution
  Mergify evaluates the freeze, but only GitHub can stop a merge made outside
  Mergify. Unless your branch requires `Mergify Merge Protections` to succeed
  (as a check, or as a deployment if you set `reporting_method: deployments`),
  someone can still merge a pull request straight from the GitHub UI while the
  freeze is active. See [Make the Check
  Required](/merge-protections/setup#make-the-check-required) to close that
  gap.
:::

## Manual Instant Freeze

Use the `Freeze Now` action for immediate blocking. It opens the same editor
without a start date: pull requests matching `Scope` are blocked the moment you
save. Set an end date and the freeze lifts itself, or leave it empty and remove
the freeze when you are done.

## Recurring Merge Windows

A freeze covers a single window: it has one start and one end, and nothing
repeats it. To block merges on a recurring basis, such as outside working hours
or every weekend, write a [merge protection
rule](/merge-protections/custom-rules) with a `schedule` condition instead:

```yaml
merge_protections:
  - name: Merge during working hours
    description: Only merge between 9am and 5pm, Monday to Friday
    if:
      - base = main
    success_conditions:
      - schedule = Mon-Fri 09:00-17:00[America/Chicago]
```

Outside the window the rule is pending, so the `Mergify Merge Protections`
check holds the pull request back the same way an active freeze does; the rule
passes again once the window reopens. See
[schedule](/configuration/data-types#schedule) for the accepted formats.

## 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, in the dashboard's
`Exceptions` section 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"
  ```
:::