Skip to main content
POST
Create a merge queue

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer <key>. An organization admin creates one in the Trunk app under Settings → Developer → API Keys and chooses the permissions it holds. A key with none can read merge queues but change nothing in them. Permissions cover merge queues and test-result uploads, including the quarantine lookups a CI run makes before it uploads; any key can call the other Flaky Tests and Dynamic CI endpoints, including their writes.

Body

application/json

Omitting mode creates a queue-mode queue, and omitting concurrency sets it to 5.

repositoryId
string<uuid>
required

The repository to create the queue for. Resolve it with GET /v2/repositories?providerUrl=….

targetBranch
string
required

The branch the queue merges into. At most one queue exists per repository and target branch.

Minimum string length: 1
mode
enum<string>

queue (shown as Single in the app) or graph (Parallel). Omitted, queue.

Available options:
queue,
graph
concurrency
integer

How many entries the queue may verify at once. Higher values merge faster and cost more CI.

Required range: 1 <= x <= 1000
bisectionConcurrency
integer

How many verification runs the engine may use in parallel when bisecting a failed batch. 0 means bisection gets no dedicated capacity and shares concurrency.

Required range: 0 <= x <= 1000
enqueueingLabel
string

The label that submits a pull request to this queue when areLabelCommandsEnabled is true. May not collide with a Trunk-reserved trunk-* state label.

Minimum string length: 1

Response

The created merge queue

id
string
required
Example:

"xK9mP2nQ"

repositoryId
string
required

Resolve with GET /v2/repositories/{id}.

Example:

"7c9e6679-7425-40de-944b-e07fc1f90ae7"

targetBranch
string
required
Example:

"main"

state
enum<string>
required

The queue's lifecycle state. switchingModes is a transient conversion state during which config and mode writes are refused.

Available options:
running,
paused,
draining,
switchingModes
Example:

"running"

mode
enum<string>
required

The engine a queue runs. queue tests entries in strict arrival order, one line. graph builds a dependency graph and may test entries speculatively in parallel, which merges faster but can require bisection to attribute a failure. Changing mode is a real conversion, not a flag flip — see mergeQueues.switchModes.

Available options:
queue,
graph
Example:

"queue"

managedState
enum<string>
required

Who owns the queue's configuration. terraform — the last write came from Terraform, identified on any queue write (create, config, pause/resume/drain, mode switch) by a User-Agent or X-Source header containing terraform or opentofu, case-insensitively — the same rule as v1. terraformWithDrift — Terraform owned it and a later write was not identified as Terraform's, so the live configuration may differ from the plan. Any such write counts, including pause/resume from other automation. manual — never written by Terraform.

Available options:
manual,
terraform,
terraformWithDrift
createdAt
string<date-time>
required

When the queue was created.

Example:

"2026-07-24T20:26:04.000Z"

updatedAt
string<date-time>
required

When the queue's own record last changed — its state or configuration. Not affected by entries moving through it.

Example:

"2026-07-28T11:02:31.000Z"

repositoryUrl
string
required

Absolute browsable URL of the repository at its provider (not a Trunk API URL).

Example:

"https://github.com/acme/widgets"

pullRequestsUrl
string
required

Path — not an absolute URL — of this queue's pull-request collection on the Trunk API. Resolve it against the server URL; do not fetch it as-is.

Example:

"/v2/merge-queues/xK9mP2nQ/pull-requests"

config
object
required

A queue's full configuration. requiredStatuses (what must pass) is a merge-protection control rather than a tuning knob, so treat write access to this object as security-relevant.

htmlUrl
string

The queue's page in the Trunk web app. Absent when the repository has no keyed organization (no slug to address it by).

Example:

"https://app.trunk.io/acme/merge-queue/xK9mP2nQ"