Scheduled Freezes

Schedule and manage merge freezes for release windows and maintenance.

Learn more: Scheduled freezes

mergify freeze list #

List scheduled freezes for a repository. Show the freezes currently configured for the repository, with their name, schedule, and state. Pass --json for machine-readable output.

Usage 
mergify freeze list [OPTIONS]
Options
--json flag

Emit the raw scheduled_freezes array as a single JSON document

Global options
-v, --verbose flag

Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this

--debug flag

Shorthand for at least debug-level logging (like -vv)

--color <COLOR> auto | always | never

When to use color in terminal output

Values: auto always never

Default: auto

-t, --token <TOKEN> string

Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL

-u, --api-url <API_URL> string

Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default

-r, --repository <REPOSITORY> string

Repository full name (owner/repo). Falls back to GITHUB_REPOSITORY env var

Environment variables
MERGIFY_API_URL

Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.

Default: https://api.mergify.com

MERGIFY_TOKEN

The Mergify credential: an application key in CI. Without it the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).

mergify freeze create #

Create a new scheduled freeze. Add a freeze that stops the merge queue from merging while it is active — for a release window, incident, or code freeze.

Usage 
mergify freeze create [OPTIONS] --reason <REASON>
Options
--reason <REASON> string required

Reason for the freeze

--timezone <TIMEZONE> string

IANA timezone name (e.g. Europe/Paris, US/Eastern). Defaults to the system timezone when omitted

-c, --condition <CONDITION> string

Matching condition (repeatable, e.g. -c base=main)

--start <START> string

Start time in ISO 8601 format (default: now)

--end <END> string

End time in ISO 8601 format (default: no end / emergency freeze)

-e, --exclude <EXCLUDE> string

Exclude condition (repeatable, e.g. -e label=hotfix)

Global options
-v, --verbose flag

Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this

--debug flag

Shorthand for at least debug-level logging (like -vv)

--color <COLOR> auto | always | never

When to use color in terminal output

Values: auto always never

Default: auto

-t, --token <TOKEN> string

Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL

-u, --api-url <API_URL> string

Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default

-r, --repository <REPOSITORY> string

Repository full name (owner/repo). Falls back to GITHUB_REPOSITORY env var

Environment variables
MERGIFY_API_URL

Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.

Default: https://api.mergify.com

MERGIFY_TOKEN

The Mergify credential: an application key in CI. Without it the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).

mergify freeze update #

Update an existing scheduled freeze. Change the settings of an existing freeze, identified by its ID. Only the fields you pass are changed; the rest are left as they are.

Usage 
mergify freeze update [OPTIONS] <FREEZE_ID>
Arguments
<FREEZE_ID> string required

Freeze ID (UUID)

Options
--reason <REASON> string

Reason for the freeze

--timezone <TIMEZONE> string

IANA timezone name

-c, --condition <CONDITION> string

Matching condition (repeatable, e.g. -c base=main). Passing the flag one or more times replaces the existing list with the values supplied. Omitting -c entirely leaves the stored list untouched

--start <START> string

Start time in ISO 8601 format

--end <END> string

End time in ISO 8601 format

-e, --exclude <EXCLUDE> string

Exclude condition (repeatable)

Global options
-v, --verbose flag

Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this

--debug flag

Shorthand for at least debug-level logging (like -vv)

--color <COLOR> auto | always | never

When to use color in terminal output

Values: auto always never

Default: auto

-t, --token <TOKEN> string

Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL

-u, --api-url <API_URL> string

Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default

-r, --repository <REPOSITORY> string

Repository full name (owner/repo). Falls back to GITHUB_REPOSITORY env var

Environment variables
MERGIFY_API_URL

Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.

Default: https://api.mergify.com

MERGIFY_TOKEN

The Mergify credential: an application key in CI. Without it the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).

mergify freeze delete #

Delete a scheduled freeze. Remove a freeze by its ID. If the freeze is currently active a reason is required, and the queue resumes merging once it's gone.

Usage 
mergify freeze delete [OPTIONS] <FREEZE_ID>
Arguments
<FREEZE_ID> string required

Freeze ID (UUID)

Options
--reason <DELETE_REASON> string

Reason for deleting the freeze (required if the freeze is currently active)

Global options
-v, --verbose flag

Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this

--debug flag

Shorthand for at least debug-level logging (like -vv)

--color <COLOR> auto | always | never

When to use color in terminal output

Values: auto always never

Default: auto

-t, --token <TOKEN> string

Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL

-u, --api-url <API_URL> string

Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default

-r, --repository <REPOSITORY> string

Repository full name (owner/repo). Falls back to GITHUB_REPOSITORY env var

Environment variables
MERGIFY_API_URL

Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.

Default: https://api.mergify.com

MERGIFY_TOKEN

The Mergify credential: an application key in CI. Without it the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).

Was this page helpful?