Update a merge queue's configuration
Requires the Update Merge Queue settings permission. Applies a JSON Merge Patch to the queue’s configuration: an absent key leaves that setting unchanged, and an unknown key is rejected rather than silently dropped. Send requiredStatuses: [], batchingRules: [] or autoRerunRules: [] to clear those lists.
requiredStatuses is a merge-protection control, not a tuning knob: it decides what must pass before an entry may merge (clearing it falls back to .trunk/trunk.yaml and the branch’s protection rules). Treat access to this endpoint as security-relevant. Refused with MODE_CHANGE_IN_PROGRESS while the queue is converting between modes, and with ALLOWED_BOT_SUBMITTERS_FROZEN for a body carrying the removed allowedBotSubmitters: bots are approved on the Bots page of the organization’s settings.
Authorizations
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.
Body
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.
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.
0 <= x <= 1000The 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.
1001How 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.
1 <= x <= 60Jobs 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.
50Response
The updated merge queue
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.
queue, graph "queue"
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.
manual, terraform, terraformWithDrift