Scheduled Freeze

Schedule merge queue freezes for maintenance or release windows.

Get scheduled freezes

GET /repos/{owner}/{repository}/scheduled_freeze

Get all the ongoing or scheduled freezes for the repository specified in the path

Authorization (any one of)
Application Key GitHub Token
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
scheduled_freezesScheduledFreezeObjectResponse[]required
idstring <uuid>required
reasonstringrequired
startstring <date-time>required
endstring <date-time> | nullrequired
timezonestringrequired
matching_conditionsMatchingConditionsDict-Output | string[]required
exclude_conditionsMatchingConditionsDict-Output | string[]
Example Response 

                          {
  "scheduled_freezes": [
    {
      "id": "string",
      "reason": "string",
      "start": "2024-01-15T09:00:00Z",
      "end": "2024-01-15T09:00:00Z",
      "timezone": "string",
      "matching_conditions": null,
      "exclude_conditions": null
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/scheduled_freeze" \
  -H "Authorization: Bearer <token>"

Create a scheduled freeze

POST /repos/{owner}/{repository}/scheduled_freeze

Create a scheduled freeze for the repository specified in the path

Authorization (any one of)
Application Key GitHub Token
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Request Body
reasonstringrequired

The reason for the scheduled freeze.

max length: 10000
startstring <date-time> | nullrequired

When the scheduled freeze begins (date and time in ISO 8601 format without TZ). Begins now if the attribute is null.

endstring <date-time> | null

When the scheduled freeze ends (date and time in ISO 8601 format without TZ).

timezonestringrequired

Timezone where the freeze is expected to happen.

matching_conditionsMatchingConditionsDict-Input | string[]

List of conditions used to match pull requests that need to be frozen during the scheduled freeze. Defaults to an empty list, which matches all pull requests.

exclude_conditionsMatchingConditionsDict-Input | string[]

List of conditions used to exclude pull requests from the scheduled freeze. Pull requests matching these conditions will not be frozen.

Responses
201 Successful Response
idstring <uuid>required
reasonstringrequired
startstring <date-time>required
endstring <date-time> | nullrequired
timezonestringrequired
matching_conditionsMatchingConditionsDict-Output | string[]required
exclude_conditionsMatchingConditionsDict-Output | string[]
Example Response 

                          {
  "id": "string",
  "reason": "string",
  "start": "2024-01-15T09:00:00Z",
  "end": "2024-01-15T09:00:00Z",
  "timezone": "string",
  "matching_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ],
  "exclude_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X POST "https://api.mergify.com/v1/repos/:owner/:repository/scheduled_freeze" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "start": "2024-01-15T09:00:00Z",
  "end": "2024-01-15T09:00:00Z",
  "timezone": "string",
  "matching_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ],
  "exclude_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ]
}'

Update a scheduled freeze

PATCH /repos/{owner}/{repository}/scheduled_freeze/{freeze_id}

Update an existing scheduled freeze on the repository specified in the path. Only the fields provided in the request body will be updated.

Authorization (any one of)
Application Key GitHub Token
Path Parameters
freeze_id string <uuid> required

The scheduled freeze `id`

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Request Body
reasonstring | null

The reason for the scheduled freeze.

startstring <date-time> | null

When the scheduled freeze begins (date and time in ISO 8601 format without TZ). Can only be updated if the scheduled freeze has not yet begun. Set to null to start now.

endstring <date-time> | null

When the scheduled freeze ends (date and time in ISO 8601 format without TZ). Set to null for an indefinite freeze.

timezonestring | null

Timezone where the freeze is expected to happen.

matching_conditionsMatchingConditionsDict-Input | string[] | null

List of conditions used to match pull requests that need to be frozen during the scheduled freeze.

exclude_conditionsMatchingConditionsDict-Input | string[] | null

List of conditions used to exclude pull requests from the scheduled freeze. Pull requests matching these conditions will not be frozen.

Responses
200 Successful Response
idstring <uuid>required
reasonstringrequired
startstring <date-time>required
endstring <date-time> | nullrequired
timezonestringrequired
matching_conditionsMatchingConditionsDict-Output | string[]required
exclude_conditionsMatchingConditionsDict-Output | string[]
Example Response 

                          {
  "id": "string",
  "reason": "string",
  "start": "2024-01-15T09:00:00Z",
  "end": "2024-01-15T09:00:00Z",
  "timezone": "string",
  "matching_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ],
  "exclude_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ]
}
400 The scheduled freeze `start` attribute cannot be updated, because the scheduled freeze has already started
403 Forbidden
404 The scheduled freeze with the given id does not exist
409 Conflict
422 Unprocessable entity
Example Request 
curl -X PATCH "https://api.mergify.com/v1/repos/:owner/:repository/scheduled_freeze/:freeze_id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "start": "2024-01-15T09:00:00Z",
  "end": "2024-01-15T09:00:00Z",
  "timezone": "string",
  "matching_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ],
  "exclude_conditions": [
    {
      "and": null,
      "or": null,
      "not": {}
    }
  ]
}'

Delete a scheduled freeze

DELETE /repos/{owner}/{repository}/scheduled_freeze/{freeze_id}
Deprecated

Delete an existing scheduled freeze on the repository specified in the path

Authorization (any one of)
Application Key GitHub Token
Path Parameters
freeze_id string <uuid> required

The scheduled freeze `id`

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Request Body
delete_reasonstringrequired

The reason for the deletion

Responses
204 Successful Response
403 Forbidden
404 The scheduled freeze with the given id does not exist
409 Conflict
422 Unprocessable entity
Example Request 
curl -X DELETE "https://api.mergify.com/v1/repos/:owner/:repository/scheduled_freeze/:freeze_id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "delete_reason": "string"
}'

Delete a scheduled freeze

POST /repos/{owner}/{repository}/scheduled_freeze/{freeze_id}/delete

Delete an existing scheduled freeze on the repository specified in the path

Authorization (any one of)
Application Key GitHub Token
Path Parameters
freeze_id string <uuid> required

The scheduled freeze `id`

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Request Body
delete_reasonstringrequired

The reason for the deletion

Responses
204 Successful Response
403 Forbidden
404 The scheduled freeze with the given id does not exist
409 Conflict
422 Unprocessable entity
Example Request 
curl -X POST "https://api.mergify.com/v1/repos/:owner/:repository/scheduled_freeze/:freeze_id/delete" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "delete_reason": "string"
}'

Was this page helpful?