Queue settings

Fabric accepts changes through a gated queue: a change only lands once its checks pass against the exact state it would produce on trunk. You tune that queue with a file at .fabric/queue.toml. Like fabric.yaml, it is an ordinary tracked file, versioned in the operation log and edited through a change.

Every knob is optional. A repo with no queue.toml gets a safe default: changes land one at a time, a suspected-flaky check is retried, and a red batch is bisected to find the culprit. You only write down what you want to change.

Where it lives and how it is read

.fabric/queue.toml sits at the repository root. A subtree can override it with its own .fabric/queue.toml under that subtree’s path, which wins for accepts that target the subtree.

The settings that govern an accept are always read from the current trunk, never from the change being evaluated. This is deliberate: a change that edits queue.toml to weaken a gate cannot use the weakened gate to let itself in. The new settings take effect only once the change lands on trunk under the old ones.

Knobs

# Checks that must pass before a change can land. A name matches a check by its
# job name or "workflow / job" title. Empty (the default) requires nothing.
required_checks = ["ci", "security"]

# How many queued changes are checked together. A bare integer is a fixed size;
# a { min, max } table is an adaptive range. Defaults to 1 (serial accepts).
batch_size = 1
# batch_size = { min = 2, max = 8 }

# How long the queue holds a partial batch before checking it anyway, so a slow
# trickle of changes still lands promptly. Defaults to off.
batch_max_wait = "30s"

# How many check batches may run at once. Unset derives a safe value from the
# runner's memory budget.
max_parallel = 3

# The wall-clock budget for a single check run. A run past it is ejected so a
# hung check never wedges the queue.
check_timeout = "10m"

# Halt the queue after a red batch instead of continuing, so a human can look
# before more changes pile on. Defaults to false.
pause_on_red = false

# How far a change's base may lag trunk before it must rebase rather than be
# speculatively merged. 0 (the default) means no cap.
max_divergence = 0

# What to do when a batch goes red: "bisect" (default) splits the batch to
# isolate the culprit; "one_at_a_time" falls back to serial accepts.
on_batch_fail = "bisect"

[retry]
# How many times a suspected-flaky red re-runs the identical state before the
# change is ejected. 0 disables retry. Defaults to 2.
max = 2
# The probability of a real failure at or above which a red is treated as a
# genuine break and ejects immediately. Below it, the check is re-run.
flake_threshold = 0.5

Organization floors

Some policy should never be weakened by a file that any writer can edit. The organization can set floors that are enforced on top of queue.toml:

Required checks that can never be disabled. These are always required, even if queue.toml omits them.
A batch-size ceiling. Batching is clamped to this cap no matter what the file asks for.

Floors live in the hub, not in the repo. Anyone with vcs:read can see the effective settings and the floors under a repo’s Settings, Accept queue; changing a floor requires vcs:manage.