Merge Queue

Control merge queue state — pause, unpause, and inspect status.

Get branches with active merge queues #

GET /repos/{owner}/{repository}/merge-queue/branches

Get the list of branches that currently have active merge queues

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth 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 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
branchesstring[]required

List of branches with active merge queues

Example Response 
                          {
  "branches": [
    "string"
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/branches" \
  -H "Authorization: Bearer <token>"

Get the current status of the merge queue #

GET /repos/{owner}/{repository}/merge-queue/status

Get the current status of the speculative checks, batches, and queued pull requests in the merge queue

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth 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 · max length: 100 · pattern: ^[\w\-\.]+$

Query Parameters
branch string

The name of the branch

Responses
200 Successful Response
batchesMergeQueueStatusBatchWithSubBatch[]required
idstring <uuid>required
namestringrequired
parent_idsstring <uuid>[]required
statusBatchStatusrequired
code"running" | "bisecting" | "preparing" | "failed" | "merged" | "waiting_for_merge" | "waiting_for_previous_batches" | "waiting_for_requeue" | "waiting_schedule" | "waiting_for_batch" | "waiting_for_checks_slot" | "frozen"required
Enum: running bisecting preparing failed merged waiting_for_merge waiting_for_previous_batches waiting_for_requeue waiting_schedule waiting_for_batch waiting_for_checks_slot frozen see Batch Status
batch_filled_slotsinteger | null
max_batch_slotsinteger | null
batch_max_start_atstring <date-time> | null
retriesinteger
max_retriesinteger
started_atstring <date-time> | nullrequired
estimated_merge_atstring <date-time> | nullrequired
estimated_ci_finish_atstring <date-time> | nullrequired
ci_finished_atstring <date-time> | nullrequired
scopesstring[]required
queue_rule_namestringrequired
checks_summaryBatchChecksSummaryrequired
passedintegerrequired
totalintegerrequired
pull_requestsMergeQueueStatusPullRequest[]required
numberintegerrequired
min: 1 · max: 9223372036854776000
titlestringrequired
urlstringrequired
authorPullRequestAuthorrequired
idintegerrequired
loginstringrequired
avatar_urlstring | nullrequired

The account's avatar URL, as GitHub reports it. Null when it is not known.

queued_atstring <date-time>required
priority_aliasstringrequired
priority_rule_namestringrequired
labelsstring[]required
scopesstring[]required
queue_state_labelsstring[]required

The names of the labels the merge queue configuration has Mergify add for a pull request's queue state (`merge_queue.queued_label`, `merge_queue.checking_label` and `merge_queue.dequeued_label`), rendered for this pull request. The pull request does not necessarily carry all of them: they are listed so a client can tell them apart from its other labels, since this status already reports the queue state they stand for. Empty when none of these options is set.

all_scopesboolean | null

Whether the pull request impacts every scope (a merge-queue barrier that cannot run in parallel with any other scope). `false` for an ordinary scoped pull request.

github_labelsPullRequestLabel[] | null
idintegerrequired
namestringrequired
colorstringrequired
defaultbooleanrequired
estimated_merge_atstring <date-time> | null
estimated_ci_finish_atstring <date-time> | null
conflict_with_pull_requestsinteger[] | null
conflict_resolution_advicestring | null

Set on a waiting pull request held back by a conflict that automatic conflict resolution could merge if it were turned on, or if the queue used a merge method that applies it: a one-line hint saying so and where to turn it on, as the markdown the pull request's conflict reason carries. `null` otherwise: on a queue whose `conflict_resolvers` already ran, and on a conflict no strategy is handed, such as a file deleted on one side.

batch_reasonBatchReason | null
kind"scope" | "directory" | "queue_order"required
Enum: scope directory queue_order
shared_scopesstring[]required
shared_directoriesstring[]required
peer_pull_request_numbersinteger[]required
affinity_scorenumberrequired
is_frozenboolean | null

Whether an ongoing scheduled freeze holds this pull request's merge, independent of its CI status — it can be running CI and `is_frozen` at once. `false` when no freeze affects it.

dequeue_requestedboolean | null

Whether a manual removal from the queue is pending for this pull request: it was removed via the 'Remove from queue' action / `@mergifyio dequeue` command (or is a stacked pull request that cascade removes with one), and is awaiting completion. The pull request remains listed until it is actually removed. `false` when no manual removal is pending; automatic dequeues (merge, CI failure, push) do not set it.

depends_on_pull_requestsinteger[] | null

Pull request numbers this one is queued behind because it depends on them: the same-repo stack predecessors the merge queue holds it behind (it declared a `Depends-On:` on the stack). It merges after them. `null` when there is no such queued dependency.

all_scopesboolean | null

Whether the batch impacts every scope (a merge-queue barrier that cannot run in parallel with any other batch). `false` for an ordinary scoped batch.

checks_timeout_atstring <date-time> | null

When the checks will time out and the batch be dequeued, if a checks timeout applies

intermediate_results_skippedboolean

True when this batch merged (or is set to merge) without its own CI passing, because a later downstream batch that includes its changes succeeded (skip_intermediate_results).

queue_pull_request_numberinteger | null

The number of the pull request the batch's checks run on: the batch pull request, or the user's own pull request for in-place checks. None while the batch has no active check pull request (still preparing, or its creation failed).

frozen_batch_aheadFrozenBatchAhead | null

The batch ahead a scheduled freeze holds, and with it this batch: this batch merges only once that one has, however green its own checks are. The batch ahead may still be running its checks. `null` when no frozen batch is ahead, including when this batch is frozen itself, which its pull requests' `is_frozen` reports.

idstring <uuid>required

The id of the batch ahead, as `batches` or a bisection's `sub_batches` list it.

pull_request_numbersinteger[]required

The pull requests queued in the batch ahead.

sub_batchesMergeQueueStatusBatchWithSubBatch[] | null
MergeQueueStatusBatchWithSubBatch (circular)
waiting_pull_requestsMergeQueueStatusPullRequest[]required
numberintegerrequired
min: 1 · max: 9223372036854776000
titlestringrequired
urlstringrequired
authorPullRequestAuthorrequired
idintegerrequired
loginstringrequired
avatar_urlstring | nullrequired

The account's avatar URL, as GitHub reports it. Null when it is not known.

queued_atstring <date-time>required
priority_aliasstringrequired
priority_rule_namestringrequired
labelsstring[]required
scopesstring[]required
queue_state_labelsstring[]required

The names of the labels the merge queue configuration has Mergify add for a pull request's queue state (`merge_queue.queued_label`, `merge_queue.checking_label` and `merge_queue.dequeued_label`), rendered for this pull request. The pull request does not necessarily carry all of them: they are listed so a client can tell them apart from its other labels, since this status already reports the queue state they stand for. Empty when none of these options is set.

all_scopesboolean | null

Whether the pull request impacts every scope (a merge-queue barrier that cannot run in parallel with any other scope). `false` for an ordinary scoped pull request.

github_labelsPullRequestLabel[] | null
idintegerrequired
namestringrequired
colorstringrequired
defaultbooleanrequired
estimated_merge_atstring <date-time> | null
estimated_ci_finish_atstring <date-time> | null
conflict_with_pull_requestsinteger[] | null
conflict_resolution_advicestring | null

Set on a waiting pull request held back by a conflict that automatic conflict resolution could merge if it were turned on, or if the queue used a merge method that applies it: a one-line hint saying so and where to turn it on, as the markdown the pull request's conflict reason carries. `null` otherwise: on a queue whose `conflict_resolvers` already ran, and on a conflict no strategy is handed, such as a file deleted on one side.

batch_reasonBatchReason | null
kind"scope" | "directory" | "queue_order"required
Enum: scope directory queue_order
shared_scopesstring[]required
shared_directoriesstring[]required
peer_pull_request_numbersinteger[]required
affinity_scorenumberrequired
is_frozenboolean | null

Whether an ongoing scheduled freeze holds this pull request's merge, independent of its CI status — it can be running CI and `is_frozen` at once. `false` when no freeze affects it.

dequeue_requestedboolean | null

Whether a manual removal from the queue is pending for this pull request: it was removed via the 'Remove from queue' action / `@mergifyio dequeue` command (or is a stacked pull request that cascade removes with one), and is awaiting completion. The pull request remains listed until it is actually removed. `false` when no manual removal is pending; automatic dequeues (merge, CI failure, push) do not set it.

depends_on_pull_requestsinteger[] | null

Pull request numbers this one is queued behind because it depends on them: the same-repo stack predecessors the merge queue holds it behind (it declared a `Depends-On:` on the stack). It merges after them. `null` when there is no such queued dependency.

mode"serial" | "parallel" | "isolated"required
Enum: serial parallel isolated
forming_batchesMergeQueueStatusFormingBatch[]

Batches still collecting pull requests, which hold no place in the merge order yet; their pull requests are listed in `waiting_pull_requests`. A filling batch can also be listed in `batches`, with the `waiting_for_batch` status.

queue_rule_namestringrequired

The queue rule the batch fills under.

scopesstring[]required

The scopes its pull requests impact, sorted.

all_scopesbooleanrequired

Whether one of its pull requests impacts every scope, which makes it a merge-queue barrier.

pull_request_numbersinteger[]required

Its pull requests, in the order the batch holds them. Each is listed in `waiting_pull_requests` too.

max_batch_slotsintegerrequired

The most pull requests its queue rule batches together.

batch_max_start_atstring <date-time>required

When it stops waiting for more pull requests: its oldest pull request's arrival plus the queue rule's `batch_max_wait_time`. It becomes a batch by then at the latest.

scope_queuesobject
pauseMergeQueuePauseResponse | null
pausedbooleanrequired

Whether the merge queue is currently paused

reasonstring | null

The reason of the merge queue pause

paused_atstring <date-time> | null

The date and time when the merge queue was paused

automatic_conflict_resolution_unsupportedboolean
Example Response 
                          {
  "scope_queues": {
    "__default__": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002"
    ]
  },
  "batches": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "parent_ids": [],
      "name": "Batch 1",
      "status": {
        "code": "running"
      },
      "started_at": "2025-11-05T14:05:00Z",
      "estimated_merge_at": "2025-11-05T14:35:00Z",
      "estimated_ci_finish_at": "2025-11-05T14:34:30Z",
      "ci_finished_at": "2025-11-05T14:34:30Z",
      "scopes": [
        "frontend",
        "backend"
      ],
      "queue_rule_name": "default",
      "checks_summary": {
        "passed": 45,
        "total": 67
      },
      "pull_requests": [
        {
          "number": 1421,
          "title": "feat(auth): add \"Reset Password\" flow to login UI",
          "url": "https://github.com/org/repo/pull/1421",
          "author": {
            "id": 123,
            "login": "james"
          },
          "queued_at": "2025-11-05T13:30:00Z",
          "priority_alias": "high",
          "priority_rule_name": "hotfix",
          "labels": [
            "feature",
            "auth"
          ],
          "github_labels": [
            {
              "id": 1,
              "name": "feature",
              "color": "0e8a16",
              "default": false
            },
            {
              "id": 2,
              "name": "auth",
              "color": "1d76db",
              "default": false
            }
          ],
          "scopes": [
            "frontend"
          ]
        }
      ]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "parent_ids": [
        "550e8400-e29b-41d4-a716-446655440001"
      ],
      "name": "Batch 2",
      "status": {
        "code": "bisecting"
      },
      "started_at": "2025-11-05T13:35:00Z",
      "estimated_merge_at": "2025-11-05T15:35:00Z",
      "estimated_ci_finish_at": "2025-11-05T15:34:30Z",
      "ci_finished_at": "2025-11-05T14:34:30Z",
      "scopes": [
        "frontend"
      ],
      "queue_rule_name": "default",
      "checks_summary": {
        "passed": 15,
        "total": 28
      },
      "sub_batches": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "parent_ids": [],
          "name": "Sub Batch 1",
          "status": {
            "code": "merged"
          },
          "started_at": "2025-11-05T13:40:00Z",
          "estimated_merge_at": "2025-11-05T13:50:00Z",
          "estimated_ci_finish_at": "2025-11-05T13:49:30Z",
          "ci_finished_at": "2025-11-05T13:49:30Z",
          "scopes": [
            "frontend"
          ],
          "queue_rule_name": "default",
          "checks_summary": {
            "passed": 15,
            "total": 15
          },
          "pull_requests": []
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440004",
          "parent_ids": [],
          "name": "Sub Batch 2",
          "status": {
            "code": "running"
          },
          "started_at": "2025-11-05T13:50:00Z",
          "estimated_merge_at": "2025-11-05T14:00:00Z",
          "estimated_ci_finish_at": "2025-11-05T13:59:30Z",
          "ci_finished_at": "2025-11-05T14:34:30Z",
          "scopes": [
            "frontend"
          ],
          "queue_rule_name": "default",
          "checks_summary": {
            "passed": 0,
            "total": 13
          },
          "pull_requests": []
        }
      ],
      "pull_requests": []
    }
  ],
  "forming_batches": [
    {
      "queue_rule_name": "default",
      "scopes": [
        "backend"
      ],
      "all_scopes": false,
      "pull_request_numbers": [
        1440
      ],
      "max_batch_slots": 5,
      "batch_max_start_at": "2025-11-05T14:52:00Z"
    }
  ],
  "waiting_pull_requests": [
    {
      "number": 1440,
      "title": "fix(api): retry the S3 client",
      "url": "https://github.com/org/repo/pull/1440",
      "author": {
        "id": 123,
        "login": "james"
      },
      "queued_at": "2025-11-05T14:42:00Z",
      "priority_alias": "medium",
      "priority_rule_name": "<default>",
      "labels": [],
      "github_labels": [],
      "scopes": [
        "backend"
      ]
    }
  ],
  "automatic_conflict_resolution_unsupported": false
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/status" \
  -H "Authorization: Bearer <token>"

Get a pull request in the merge queue #

GET /repos/{owner}/{repository}/merge-queue/pull/{pr_number}

Get details about a specific pull request in the merge queue

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth GitHub Token
Path Parameters
pr_number integer required

The pull request number

min: 1 · max: 9223372036854776000

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 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
numberintegerrequired

The number of the pull request

min: 1 · max: 9223372036854776000
queued_atstring <date-time>required

The timestamp when the pull request entered the queue

estimated_time_of_mergestring <date-time> | nullrequired

The estimated timestamp when this pull request will be merged

positionintegerrequired

The position of the pull request in the queue (0-indexed)

priority_rule_namestringrequired

The name of the priority rule applied to this pull request

queue_rule_namestringrequired

The name of the queue rule

checks_timeout_atstring <date-time> | nullrequired

The timestamp when the checks will timeout for this pull request

queue_ruleQueueRulerequired

The queue rule associated to this pull request

namestringrequired

The name of the queue rule

configobjectrequired

The configuration of the queue rule

mergeability_checkMergeQueueMergeabilityCheck | nullrequired

The current state of the mergeability check

check_type"in_place" | "draft_pr" | "trusted"required

The type of queue check: `in_place` (checks run on the pull request itself), `draft_pr` (checks run on a Mergify draft pull request), or `trusted` (no queue CI run is required: the merge relies on the pull request's own green CI, either because it already contains the base branch tip or because the base commits it is missing do not affect its scopes — the latter is Direct Merge, see https://docs.mergify.com/merge-queue/direct-merge).

Enum: in_place draft_pr trusted
queue_pull_request_numberintegerrequired

The number of the pull request used by the speculative check

min: 1 · max: 9223372036854776000
started_atstring <date-time> | nullrequired

The timestamp when the checks started for this pull request

ci_ended_atstring <date-time> | nullrequired

The timestamp when the CI ended for this pull request

ci_state"pending" | "success" | "failed"required

The combined state of the CI checks

Enum: pending success failed
statestringrequired

The overall queue check conclusion

checksQueueCheck[]required

The list of pull request checks

namestringrequired

Check name

descriptionstringrequired

Check description

urlstring | nullrequired

Check detail url

details_urlstring | null

External integrator's direct URL (e.g. Jenkins build URL)

state"failure" | "error" | "cancelled" | "action_required" | "timed_out" | "pending" | "neutral" | "skipped" | "stale" | "success"required

Check state

Enum: failure error cancelled action_required timed_out pending neutral skipped stale success
avatar_urlstring | nullrequired

Check avatar_url

conditions_evaluationQueueConditionEvaluationJsonSerialized | nullrequired

The queue rule conditions evaluation

matchbooleanrequired
labelstringrequired
descriptionstring | nullrequired
documentation_urlstring | nullrequired
scheduleScheduleJSON | nullrequired
timezonestringrequired
daysobjectrequired
subconditionsQueueConditionEvaluationJsonSerialized[]required
matchbooleanrequired
labelstringrequired
descriptionstring | nullrequired
documentation_urlstring | nullrequired
scheduleScheduleJSON | nullrequired
timezonestringrequired
daysobjectrequired
subconditionsQueueConditionEvaluationJsonSerialized[]required
QueueConditionEvaluationJsonSerialized (circular)
evaluationsEvaluation[]required
pull_requestintegerrequired
min: 1 · max: 9223372036854776000
matchbooleanrequired
evaluation_errorstring | nullrequired
related_checksstring[]required
next_evaluation_atstring <date-time> | nullrequired
evaluationsEvaluation[]required
pull_requestintegerrequired
min: 1 · max: 9223372036854776000
matchbooleanrequired
evaluation_errorstring | nullrequired
related_checksstring[]required
next_evaluation_atstring <date-time> | nullrequired
Example Response 
                          {
  "number": 1,
  "queued_at": "2024-01-15T09:00:00Z",
  "estimated_time_of_merge": "2024-01-15T09:00:00Z",
  "position": 0,
  "priority_rule_name": "string",
  "queue_rule_name": "string",
  "checks_timeout_at": "2024-01-15T09:00:00Z",
  "queue_rule": {
    "name": "string",
    "config": {}
  },
  "mergeability_check": {
    "check_type": "in_place",
    "queue_pull_request_number": 1,
    "started_at": "2024-01-15T09:00:00Z",
    "ci_ended_at": "2024-01-15T09:00:00Z",
    "ci_state": "pending",
    "state": "string",
    "checks": [
      {}
    ],
    "conditions_evaluation": {
      "match": true,
      "label": "string",
      "description": "string",
      "documentation_url": "string",
      "schedule": {},
      "subconditions": null,
      "evaluations": null
    }
  }
}
403 Forbidden
404 `PULL_REQUEST_NOT_QUEUED`: The pull request is not in any merge queue of the repository.
detailstringrequired
error_code"CONFIGURATION_BRANCH_REFUSED" | "CONFIGURATION_REFUSED_BY_REPOSITORY_RULES" | "CONFIGURATION_SIGNED_COMMITS_REQUIRED" | "DEFAULT_BRANCH_NOT_FOUND" | "GITHUB_ACCOUNT_SUSPENDED" | "GITHUB_APP_ACCESS_LOST" | "GITHUB_RATE_LIMITED" | "GITHUB_UPSTREAM_REQUEST_FORBIDDEN" | "GITHUB_UPSTREAM_REQUEST_REJECTED" | "GITHUB_UPSTREAM_UNAVAILABLE" | "IP_ALLOW_LIST_NOT_CONFIGURED" | "NO_LOGIN_IN_PROGRESS" | "ORGANIZATION_MEMBERS_ONLY" | "PULL_REQUEST_NOT_QUEUED" | "RETRY_RULE_NOT_FOUND" | "SAML_ENFORCEMENT_NOT_AUTHORIZED" | "SETTING_MANAGED_BY_ENV" | "SETUP_ALREADY_DONE" | "SETUP_TOKEN_MISMATCH" | "SHADOW_OFFICE_UNAVAILABLE" | "SUBSCRIPTION_INACTIVE" | "SUBSCRIPTION_TOKEN_INVALID" | "TEST_ALREADY_QUARANTINED"
Enum: CONFIGURATION_BRANCH_REFUSED CONFIGURATION_REFUSED_BY_REPOSITORY_RULES CONFIGURATION_SIGNED_COMMITS_REQUIRED DEFAULT_BRANCH_NOT_FOUND GITHUB_ACCOUNT_SUSPENDED GITHUB_APP_ACCESS_LOST GITHUB_RATE_LIMITED GITHUB_UPSTREAM_REQUEST_FORBIDDEN GITHUB_UPSTREAM_REQUEST_REJECTED GITHUB_UPSTREAM_UNAVAILABLE IP_ALLOW_LIST_NOT_CONFIGURED NO_LOGIN_IN_PROGRESS ORGANIZATION_MEMBERS_ONLY PULL_REQUEST_NOT_QUEUED RETRY_RULE_NOT_FOUND SAML_ENFORCEMENT_NOT_AUTHORIZED SETTING_MANAGED_BY_ENV SETUP_ALREADY_DONE SETUP_TOKEN_MISMATCH SHADOW_OFFICE_UNAVAILABLE SUBSCRIPTION_INACTIVE SUBSCRIPTION_TOKEN_INVALID TEST_ALREADY_QUARANTINED
documentation_urlstring
Example Response 
                          {
  "detail": "string",
  "error_code": "CONFIGURATION_BRANCH_REFUSED",
  "documentation_url": "string"
}
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pull/:pr_number" \
  -H "Authorization: Bearer <token>"

Preview the impact of dequeuing a pull request #

GET /repos/{owner}/{repository}/merge-queue/pull/{pr_number}/dequeue-impact

Return how many batches would be interrupted, how many other pull requests would be rechecked, and how many stacked pull requests would also be dequeued if the given pull request is manually dequeued

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth GitHub Token
Path Parameters
pr_number integer required

The pull request number

min: 1 · max: 9223372036854776000

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 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
interrupted_batchesintegerrequired

Number of in-progress batches whose checks would be interrupted and restarted if this pull request is dequeued

rechecked_pull_requestsintegerrequired

Number of other pull requests from the interrupted batches that would be re-embarked and rechecked

cascaded_pull_requestsintegerrequired

Number of queued pull requests stacked on top of this one that would also be dequeued (excludes the dequeued pull request itself)

Example Response 
                          {
  "interrupted_batches": 0,
  "rechecked_pull_requests": 0,
  "cascaded_pull_requests": 0
}
403 Forbidden
404 `PULL_REQUEST_NOT_QUEUED`: The pull request is not in any merge queue of the repository.
detailstringrequired
error_code"CONFIGURATION_BRANCH_REFUSED" | "CONFIGURATION_REFUSED_BY_REPOSITORY_RULES" | "CONFIGURATION_SIGNED_COMMITS_REQUIRED" | "DEFAULT_BRANCH_NOT_FOUND" | "GITHUB_ACCOUNT_SUSPENDED" | "GITHUB_APP_ACCESS_LOST" | "GITHUB_RATE_LIMITED" | "GITHUB_UPSTREAM_REQUEST_FORBIDDEN" | "GITHUB_UPSTREAM_REQUEST_REJECTED" | "GITHUB_UPSTREAM_UNAVAILABLE" | "IP_ALLOW_LIST_NOT_CONFIGURED" | "NO_LOGIN_IN_PROGRESS" | "ORGANIZATION_MEMBERS_ONLY" | "PULL_REQUEST_NOT_QUEUED" | "RETRY_RULE_NOT_FOUND" | "SAML_ENFORCEMENT_NOT_AUTHORIZED" | "SETTING_MANAGED_BY_ENV" | "SETUP_ALREADY_DONE" | "SETUP_TOKEN_MISMATCH" | "SHADOW_OFFICE_UNAVAILABLE" | "SUBSCRIPTION_INACTIVE" | "SUBSCRIPTION_TOKEN_INVALID" | "TEST_ALREADY_QUARANTINED"
Enum: CONFIGURATION_BRANCH_REFUSED CONFIGURATION_REFUSED_BY_REPOSITORY_RULES CONFIGURATION_SIGNED_COMMITS_REQUIRED DEFAULT_BRANCH_NOT_FOUND GITHUB_ACCOUNT_SUSPENDED GITHUB_APP_ACCESS_LOST GITHUB_RATE_LIMITED GITHUB_UPSTREAM_REQUEST_FORBIDDEN GITHUB_UPSTREAM_REQUEST_REJECTED GITHUB_UPSTREAM_UNAVAILABLE IP_ALLOW_LIST_NOT_CONFIGURED NO_LOGIN_IN_PROGRESS ORGANIZATION_MEMBERS_ONLY PULL_REQUEST_NOT_QUEUED RETRY_RULE_NOT_FOUND SAML_ENFORCEMENT_NOT_AUTHORIZED SETTING_MANAGED_BY_ENV SETUP_ALREADY_DONE SETUP_TOKEN_MISMATCH SHADOW_OFFICE_UNAVAILABLE SUBSCRIPTION_INACTIVE SUBSCRIPTION_TOKEN_INVALID TEST_ALREADY_QUARANTINED
documentation_urlstring
Example Response 
                          {
  "detail": "string",
  "error_code": "CONFIGURATION_BRANCH_REFUSED",
  "documentation_url": "string"
}
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pull/:pr_number/dequeue-impact" \
  -H "Authorization: Bearer <token>"

Dequeue a pull request from the merge queue #

POST /repos/{owner}/{repository}/merge-queue/pull/{pr_number}/dequeue

Manually remove the given pull request (and its queued stack successors) from the merge queue

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth GitHub Token
Path Parameters
pr_number integer required

The pull request number

min: 1 · max: 9223372036854776000

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 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
204 Successful Response
403 Forbidden
404 `PULL_REQUEST_NOT_QUEUED`: The pull request is not in any merge queue of the repository.
detailstringrequired
error_code"CONFIGURATION_BRANCH_REFUSED" | "CONFIGURATION_REFUSED_BY_REPOSITORY_RULES" | "CONFIGURATION_SIGNED_COMMITS_REQUIRED" | "DEFAULT_BRANCH_NOT_FOUND" | "GITHUB_ACCOUNT_SUSPENDED" | "GITHUB_APP_ACCESS_LOST" | "GITHUB_RATE_LIMITED" | "GITHUB_UPSTREAM_REQUEST_FORBIDDEN" | "GITHUB_UPSTREAM_REQUEST_REJECTED" | "GITHUB_UPSTREAM_UNAVAILABLE" | "IP_ALLOW_LIST_NOT_CONFIGURED" | "NO_LOGIN_IN_PROGRESS" | "ORGANIZATION_MEMBERS_ONLY" | "PULL_REQUEST_NOT_QUEUED" | "RETRY_RULE_NOT_FOUND" | "SAML_ENFORCEMENT_NOT_AUTHORIZED" | "SETTING_MANAGED_BY_ENV" | "SETUP_ALREADY_DONE" | "SETUP_TOKEN_MISMATCH" | "SHADOW_OFFICE_UNAVAILABLE" | "SUBSCRIPTION_INACTIVE" | "SUBSCRIPTION_TOKEN_INVALID" | "TEST_ALREADY_QUARANTINED"
Enum: CONFIGURATION_BRANCH_REFUSED CONFIGURATION_REFUSED_BY_REPOSITORY_RULES CONFIGURATION_SIGNED_COMMITS_REQUIRED DEFAULT_BRANCH_NOT_FOUND GITHUB_ACCOUNT_SUSPENDED GITHUB_APP_ACCESS_LOST GITHUB_RATE_LIMITED GITHUB_UPSTREAM_REQUEST_FORBIDDEN GITHUB_UPSTREAM_REQUEST_REJECTED GITHUB_UPSTREAM_UNAVAILABLE IP_ALLOW_LIST_NOT_CONFIGURED NO_LOGIN_IN_PROGRESS ORGANIZATION_MEMBERS_ONLY PULL_REQUEST_NOT_QUEUED RETRY_RULE_NOT_FOUND SAML_ENFORCEMENT_NOT_AUTHORIZED SETTING_MANAGED_BY_ENV SETUP_ALREADY_DONE SETUP_TOKEN_MISMATCH SHADOW_OFFICE_UNAVAILABLE SUBSCRIPTION_INACTIVE SUBSCRIPTION_TOKEN_INVALID TEST_ALREADY_QUARANTINED
documentation_urlstring
Example Response 
                          {
  "detail": "string",
  "error_code": "CONFIGURATION_BRANCH_REFUSED",
  "documentation_url": "string"
}
409 Conflict
422 Unprocessable entity
Example Request 
curl -X POST "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pull/:pr_number/dequeue" \
  -H "Authorization: Bearer <token>"

Pause the merge queue #

PUT /repos/{owner}/{repository}/merge-queue/pause

Pause the merge of the requested repository

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth 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 · max length: 100 · pattern: ^[\w\-\.]+$

Request Body
reasonstringrequired

The reason of the merge queue pause

max length: 255
Responses
200 Successful Response
pausedbooleanrequired

Whether the merge queue is currently paused

reasonstring | null

The reason of the merge queue pause

paused_atstring <date-time> | null

The date and time when the merge queue was paused

Example Response 
                          {
  "paused": true,
  "reason": "string",
  "paused_at": "2024-01-15T09:00:00Z"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X PUT "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pause" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

Unpause merge queue #

DELETE /repos/{owner}/{repository}/merge-queue/pause

Unpause the merge queue of the requested repository

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth 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 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
204 Successful Response
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X DELETE "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pause" \
  -H "Authorization: Bearer <token>"

Get merge queue pause data #

GET /repos/{owner}/{repository}/merge-queue/pause

Checks if the merge queue is paused and returns the pause data

Authorization (any one of)
Admin Application Key MergifyTokenBearerAuth 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 · max length: 100 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
pausedbooleanrequired

Whether the merge queue is currently paused

reasonstring | null

The reason of the merge queue pause

paused_atstring <date-time> | null

The date and time when the merge queue was paused

Example Response 
                          {
  "paused": true,
  "reason": "string",
  "paused_at": "2024-01-15T09:00:00Z"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pause" \
  -H "Authorization: Bearer <token>"

Was this page helpful?