Merge Queue API (v2)

​

Before you start

​

Concepts

• Queue entry: a pull request’s place in a merge queue, under queueEntry on a pull request. Its id differs from the pull request’s id. Endpoints under /v2/pull-requests/{id} take the pull request’s id.
• Queue entry state: notReady (submitted, but waiting on a requirement such as passing checks or impacted targets), pending (ready, waiting to test), testing, testsPassed, and pendingFailure. The final states are merged, failed, and cancelled. queueEntry.readiness explains a notReady entry. A pendingFailure entry’s tests failed, and the queue holds it to learn whether the failure is its own, for example while the pull requests ahead of it finish. See Pending failure depth.
• Verification run: one CI run the queue started to test a pull request, or a batch of them. When a batch fails, the queue splits it to find the culprit (bisection). Each split is its own verification run.
• Mode: queue mode (Single in the app) puts pull requests in one line, each tested on top of the ones ahead of it, several at a time. graph mode (Parallel in the app) gives unrelated pull requests separate lines, based on the impacted targets CI uploads for each.
• Priority: lower priorityValue numbers test first. The names are urgent (0), high (10), medium (100), and low (200). Send a number as priorityValue or a name as priorityName. Without either, a pull request gets medium (100). urgent (or priorityValue: 0) restarts lower-priority pull requests that are already testing, so reserve it for emergencies. See Priority merging.
• Direct to queue: direct: true sends a pull request to the queue before its branch protection is satisfied. See Direct-to-Queue.

​

Authentication

curl https://api.trunk.io/v2/merge-queues \
  -H "Authorization: Bearer $TRUNK_API_KEY"

​

Finding IDs

1. Queue: GET /v2/merge-queues lists your organization’s queues, each with its id, repositoryId, repositoryUrl, and targetBranch. To list one repository’s queues, get its ID from GET /v2/repositories?providerUrl=https://github.com/<owner>/<repo> (.data[0].id), then call GET /v2/merge-queues?repositoryId=<id>&targetBranch=<branch>.
2. Pull request: GET /v2/pull-requests?repositoryId=…&number=… resolves up to 50 comma-separated pull request numbers at once (set limit=50, since the default page is 25), or one head branch. It finds only pull requests Trunk’s GitHub App has already seen. If you just opened one, retry shortly.

curl "https://api.trunk.io/v2/pull-requests?repositoryId=7c9e6679-7425-40de-944b-e07fc1f90ae7&number=4901" \
  -H "Authorization: Bearer $TRUNK_API_KEY"

​

Submit and wait for a merge

curl -X POST https://api.trunk.io/v2/merge-queues/xK9mP2nQ/pull-requests \
  -H "Authorization: Bearer $TRUNK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "number": 4901 }'

• If the pull request is already queued here (not yet merged, failed, or cancelled), submit returns 409 PR_ALREADY_ENQUEUED and changes nothing. Look up its id instead, using the queue’s repositoryId from GET /v2/merge-queues/{id}.
• If Trunk can’t enqueue it, submit returns 422 PR_NOT_ENQUEUEABLE with the reason in message. For example:
  • The pull request doesn’t exist.
  • It targets a different branch from the queue’s. A stacked pull request may target another pull request’s branch, as long as the stack ends at the queue’s branch.
  • A repository ruleset can block it.
  • It’s still in another of the repository’s queues. Look up the pull request, read queueEntry.mergeQueueId, and dequeue it there first.
• A closed pull request is accepted but stays notReady.

• Read queueEntry.state, not the top-level state, which is the pull request’s state on GitHub.
• queueEntry.state can go back to notReady before the entry ends. A push to the pull request sends a queued entry back to notReady to wait on the new commit, and a resubmitted pull request reuses its entry and starts again at notReady. Keep polling.
• Stop if queueEntry disappears or its mergeQueueId changes, and report the outcome as unknown. This happens when a failed or cancelled pull request is submitted to another queue, or its queue is deleted.
• Send the last response’s ETag in If-None-Match. If nothing changed, you get 304 with no body.
• Set a deadline of your own. A pull request can stay notReady for a long time; the queue cancels it only if its notReadyTimeoutMinutes setting is set.
• Don’t stop when ci.pollAfterSeconds is null. It describes CI on the pull request’s own head commit, not its place in the queue.

​

Pagination

{
  "data": [],
  "nextCursor": "AQEKZm9vYmFy",
  "hasMore": true
}

​

Errors

{
  "error": {
    "code": "MERGE_QUEUE_NOT_FOUND",
    "message": "No merge queue found with ID xK9mP2nQ"
  }
}

• 404 also means “not yours”. A read of a resource in another organization returns 404, not 403, so the API never reveals whether it exists.
• 403 INSUFFICIENT_PERMISSIONS means your credential is valid but not permitted to take that action.
• 422 means the request can’t succeed as sent. Retrying it unchanged gets the same answer until something about the pull request or repository changes.

​

Rate limits

• GET requests on paths that start with /v2/pull-requests, such as GET /v2/pull-requests/{id} and its history: 5 per second per API key or user. GET /v2/merge-queues/{id}/pull-requests uses the organization’s limit.
• Metrics (GET /v2/merge-queues/metrics and GET /v2/merge-queues/{id}/metrics): 5 per second per organization.
• Impacted-target uploads from a GitHub Actions login: 10 per second per repository, with a separate allowance for fork pull requests.

​

Retrying

• Reads are safe to retry on 429, 500, 502, 503, 504, and network errors. Back off exponentially between attempts.
• Writes don’t honor Idempotency-Key yet. A write that times out or returns 500, 502, 503, or 504 has an unknown outcome, so read the resource back before retrying. A blind retry can, for example, restart a pull request’s tests twice. Some writes, such as PATCH …/config and PUT /v2/impacted-targets, set a value and are safe to repeat.

​

Compatibility

​

Endpoints

​

Merge queues

​

Queue order

​

Pull requests

​

Testing

​

Impacted targets

​

Metrics

​

Repositories