Mergify Queue Command

The queue command in Mergify offers users a direct way to interact with the Mergify merge queue, right from their pull request comments. With this command, users can add a pull request to a merge queue or re-add it after it has been dequeued.

To enter a queue, a pull request must match the queue_conditions of a queue rule. See Adding a pull request to the merge queue for more details.

@mergifyio queue

The command takes no arguments: the pull request waits until it matches the queue_conditions of a queue rule, then enters the queue under the first rule it matches.

If a pull request was removed from the merge queue (due to a failed check, a flaky test, or a manual dequeue), you can re-add it using the same queue command:

@mergifyio queue

The command resets the pull request status and places it back in the merge queue, allowing Mergify to retry validation.

A queue command stays pending until the pull request matches a queue rule’s queue_conditions, so a second one can arrive while the first is still waiting. A second @mergifyio queue is then ignored, and Mergify answers that it is already running from a previous command.

To call off a pending queue command, use the dequeue command.

If someone pushes to the pull request while a queue command is still waiting for queue_conditions to match, Mergify cancels the command and replies that new commits were pushed, naming who pushed them. The command vouches for the commits its author could see, so review the new ones and run @mergifyio queue again.

Mergify’s own pushes don’t count, so an update or a rebase that brings the pull request up to date leaves the pending command alone. Once the pull request has entered the queue, a push takes it out of the queue instead of cancelling a pending command.

If you’d rather not type a command, Mergify can post a checkbox you can tick to queue your pull request:

• Queue this pull request comes in a comment of its own. Mergify posts it on every open pull request one of your queue rules covers, unless the pull request is a draft, is already queued, has a merge queue status comment, or is queued automatically by your configuration. Tick it to add the pull request to the merge queue: if it doesn’t match its queue_conditions yet, it waits and enters the queue once they pass. If someone pushes new commits while it waits, the request is cancelled. If status_comments is all, the default, the checkbox then comes back in the status comment, so you can tick it again.

• Requeue this pull request comes in the merge queue status comment, after the pull request has left the queue without being merged. Tick it to put the pull request back in the queue.

Ticking a checkbox does exactly what the @mergifyio queue command does. The action is attributed to the person who ticked it, and the same command restrictions and write-permission checks apply, so a checkbox can’t queue a pull request that the person couldn’t queue manually.

This is enabled by default. To turn it off, set queue_controls_comment to false in your merge_queue configuration:

merge_queue:
  queue_controls_comment: false

A script or a bot can queue a pull request without posting a comment, by calling the Mergify API:

curl -X POST \
     -H "Authorization: Bearer <token>" \
     https://api.mergify.com/v1/repos/<owner>/<repository>/merge-queue/pull/<number>/queue

The request has no body and names no queue. It does what @mergifyio queue does: the pull request waits until it matches the queue_conditions of a queue rule, then enters the queue under the first rule it matches. A push while it waits cancels the request, as described in Pushing while the command waits.

Mergify answers 202 Accepted once it has recorded the request, which can be long before the pull request enters the queue. To follow what happens next, read the pull request’s queue status or its events.

The call needs an application key granted Merge Queue at Read & write, or a Mergify user token whose owner can write to the repository. The command restrictions set for queue apply to it as they apply to a comment. A user token is judged as the person it belongs to. An application key belongs to no one, so it is judged with admin permission and no sender: it passes sender-permission >= write, and fails a condition requiring a given sender, such as sender = @team.

When Mergify refuses the request, the response body carries an error_code next to the detail message:

Queueing a pull request that is already in the queue, for example, answers:

{
  "detail": "Pull request `123` is already queued",
  "error_code": "PULL_REQUEST_ALREADY_QUEUED"
}

To take the pull request out again, or to call off a request that is still waiting, use the dequeue endpoint. The API Reference lists both endpoints with their responses.

A request made through the API shows up in the pull request’s events like a command posted in a comment: as a command.queue event, or command.dequeue for a dequeue. You can read it in the dashboard, with mergify events, or through the Activity Log API. These fields tell who asked and how:

• command_trigger is api for a request made through the API, and dashboard for one made from the Mergify dashboard.

• requested_by names who asked: the user behind the token, or the application key. requested_by_staff is true when Mergify staff made the request while helping you.

• author is null when an application key or Mergify staff made the request; read requested_by instead.

• comment_id is null, since no comment carried the command.