Skip to main content
PATCH
Update a merge queue's configuration

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 new key starts with no permissions: it can read merge queues but change nothing in them, and it cannot get a Dynamic CI plan. Each endpoint that needs a permission names it in its description; the Dynamic CI plan endpoints need Generate Dynamic CI plans.

Path Parameters

id
string
required

The merge queue's id.

Example:

"xK9mP2nQ"

Body

application/json

A JSON Merge Patch: an absent key leaves that setting unchanged, and an unknown key is rejected rather than dropped. requiredStatuses: [], batchingRules: [] and autoRerunRules: [] clear those lists. A batchingRules or autoRerunRules write replaces the whole set. notReadyTimeoutMinutes must be a whole number of hours.

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, separate from concurrency. At least 1.

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

How many test runs behind an entry in pendingFailure may keep testing while it waits; a passing run behind it shows the failure was not its own. Applies with canOptimisticallyMerge. 0 means nothing behind a pending failure tests until it resolves.

Required range: 0 <= x <= 1000
canOptimisticallyMerge
boolean

Whether an entry whose own verification passed may merge before every entry ahead of it has merged, when the engine can prove the result still holds.

allowBatching
boolean

Whether the queue may verify several entries together in one run. Batching is cheaper but a failure must then be attributed by bisection. An individual entry can opt out at submit time; the queue setting is the ceiling, so an entry cannot batch when this is false.

batchingMaxWaitTimeMinutes
integer

How long the queue waits for more entries before starting a batch smaller than batchingMinSize. 0 means never wait — start as soon as there is anything to test.

Required range: 0 <= x <= 10080
batchingMinSize
integer

The batch size the queue prefers before starting a run, subject to batchingMaxWaitTimeMinutes. At least 1.

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

How long a verification run may take before the queue abandons it and fails the entry. 0 means no timeout — a stuck run will hold its slot indefinitely.

Required range: 0 <= x <= 10080
notReadyTimeoutMinutes
integer

How long an entry may sit notReady before the queue cancels it (NOT_READY_TIMEOUT_EXPIRED). 0 means no timeout. Stored as whole hours, so this must be a multiple of 60.

Required range: 0 <= x <= 43200
createsPrsForTestingBranches
boolean

Whether the queue opens a provider pull request for each testing branch it creates. Makes runs visible in the provider UI at the cost of extra pull-request noise.

areCommentsEnabled
boolean

Whether the queue posts status comments on pull requests it processes.

areCommandsEnabled
boolean

Whether the queue acts on comment commands (e.g. a comment asking to enqueue or dequeue).

isStatusCheckEnabled
boolean

Whether the queue publishes its own status check onto each pull request, so its state is visible in the provider's merge box.

isExtensionEnabled
boolean

Whether Trunk's browser extension surfaces queue controls on this repository's pull requests.

areLabelCommandsEnabled
boolean

Whether applying enqueueingLabel to a pull request submits it to this queue.

areStateLabelsEnabled
boolean

Whether the queue maintains labels reflecting each entry's state. Trunk owns labels prefixed trunk-, which is why enqueueingLabel may not collide with that prefix.

requiredStatuses
string[]

The provider check names that must pass for an entry to be considered verified. Empty means the queue takes required statuses from .trunk/trunk.yaml, then from the branch's protection rules. If .trunk/trunk.yaml doesn't set them and the branch requires no checks, the entry fails with START_TEST_RUN_NO_REQUIRED_STATUSES; an explicit empty list in .trunk/trunk.yaml gates on nothing. Security-relevant: this is the queue's merge gate.

Maximum array length: 100
Minimum string length: 1
batchingRules
object[]

Rules changing how pull requests are batched based on the build targets they impact. Empty means every entry batches normally. Applies to queues in graph mode that upload impacted targets.

Maximum array length: 100
directMergeMode
enum<string>

One of off or always. See the DirectMergeMode schema.

Available options:
off,
always
optimizationMode
enum<string>

One of off or bisectionSkipRedundantTests. See the OptimizationMode schema.

Available options:
off,
bisectionSkipRedundantTests
mergeMethod
enum<string>

One of mergeCommit, squash, or rebase. See the MergeMethod schema.

Available options:
mergeCommit,
squash,
rebase
isMergeMethodOverrideEnabled
boolean

Whether whoever submits a pull request may choose its merge method. An entry that chooses none merges with the queue's mergeMethod. While false, every entry merges with the queue's mergeMethod, and a submit that changes an entry's merge method is refused.

testBranchConstructionMode
enum<string>

One of renameTempBranch or pushNewBranchFromTemp. See the TestBranchConstructionMode schema.

Available options:
renameTempBranch,
pushNewBranchFromTemp
failedTestRunTeardown
enum<string>

One of tearDown or keepForRerun. See the FailedTestRunTeardown schema.

Available options:
tearDown,
keepForRerun
maxHoldMinutes
integer

How long a re-run of failed checks (POST /v2/pull-requests/{id}/rerun-failed-checks) keeps its pull request in pendingFailure waiting for the re-run to start; rerun.until is the request time plus this. From 1 to 60. Applies while failedTestRunTeardown is keepForRerun. A change applies to later re-runs; a hold already in progress keeps its rerun.until.

Required range: 1 <= x <= 60
autoRerunRules
object[]

Jobs that Trunk re-runs automatically when a verification run fails a required check. A rule starts when a job it names fails in the same workflow as a failed required check: Trunk re-runs the failed jobs of that workflow, at once (now) or when the workflow finishes (wait), up to maxReruns times. These re-runs and POST /v2/pull-requests/{id}/rerun-failed-checks share two re-runs per verification run. When jobs from more than one rule fail, the first of those rules applies, so the order of rules is significant; the order of checks within a rule is not, and a resend in another order changes nothing. A check can be in only one rule. Requires failedTestRunTeardown: keepForRerun and a GitHub repository; a check that Trunk cannot re-run is refused with VALIDATION_FAILED, naming the check. Empty means no rules.

Maximum array length: 50
Example:
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 updated 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"