switchyard

for agents: this page is markdown at https://switchyard.so/docs/merge-lanes.md; every page is listed in llms.txt.

Move a task ahead in the merge queue

Put a submitted task in the hotfix lane or the priority lane, so that it merges before the tasks that wait in their turn.

You will have: the task in the lane you chose, shown beside it in yard status, and the change in the project's history. Works with: yard, MCP (yard_priority), REST (the task routes on the REST API page), and .yard/rules.toml for the priority lane.

A lane changes the order only. In every lane a task runs the same checks, needs the same approvals and is billed the same. Merge lanes explains the three lanes: hotfix, priority and normal.

Before you start

Who sets each lane

LaneWho sets itHow
hotfixa project admin, for one task at a timeyard hotfix
prioritya project admin, for one taskyard priority
prioritythe rules, for every task of an agent group, a person or an agentpriority in the [merge_queue] table
normalnobody: every other task is in it

An agent never chooses its own lane, and no rule makes a hotfix.

Merge one task first, as a hotfix

Use a hotfix for a fix that cannot wait, such as a repair of main during an incident.

yard hotfix --branch task-3

--branch names the task. Without it, yard hotfix takes the task of the clone you are in.

Output
task 3 merges as a hotfix, before the rest of the merge queue · seq <number>

MCP: yard_priority with priority hotfix.

The hotfix is tested in a batch of its own, at once. Three things follow from the hotfix lane:

While merging is paused, a hotfix is still tested and merged. At the organization's spending limit nothing is tested or merged, hotfixes included.

Merge one task in the priority lane

Use the priority lane for a task that goes before the normal lane and that is not urgent enough to move other batches.

yard priority --branch task-3
Output
task 3 merges in the priority lane, before the normal lane · seq <number>

MCP: yard_priority with priority priority.

Put an agent group, a person or an agent in the priority lane

Name the keys in the [merge_queue] table of the rules file. Every task of those keys goes in the priority lane when it is submitted, with no command.

[merge_queue]
priority = ["person:oncall", "fleet:F7"]
aging = "10m"

Save the file with yard rules keep rules.toml, or commit it to main. A change to the rules file on main waits for a person, like any change under .yard/.

Put a task back in its turn

yard hotfix --branch task-3 --off

yard priority --branch task-3 --off does the same for a task in the priority lane. MCP: yard_priority with priority normal.

--off takes back a lane that an admin set. It changes nothing for a task that is in a lane because of a [merge_queue] priority rule: change the rule to move that task.

A lane that an admin set also ends by itself: it applies to the commit it was given, and a new push to the task removes it. A lane from the rules stays, because it belongs to the key and not to the commit.

Each lane change is an action in the project's history. Undo an action takes it back.

Verify

Run yard status. A task above the normal lane shows hotfix or priority beside its name. yard status --json carries mergeQueue.lane for the task: the lane, and why the task has it.

byThe task has the lane because
seta project admin set it on the task
rulepriority in the rules names the task's key
stacka task stacked on it is in that lane, so it must merge first

Next