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
- You are a project admin: an owner or admin of the organization, signed in with
yard login https://app.switchyard.so --github, or you hold the project admin key. A task key, an agent group key, a developer and a member are refused. - The task is submitted. A lane is refused for a task that is not in the merge queue.
Who sets each lane
| Lane | Who sets it | How |
|---|---|---|
| hotfix | a project admin, for one task at a time | yard hotfix |
| priority | a project admin, for one task | yard priority |
| priority | the rules, for every task of an agent group, a person or an agent | priority in the [merge_queue] table |
| normal | nobody: 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:
- Once for each push. The hotfix goes ahead of the batches whose checks have not started. It does so once for the commit it was given. A hotfix whose own test build fails does not move the same batches back again. A new push to the task, submitted and made a hotfix again, gets one more turn.
- A running check is never stopped. A batch whose checks have started keeps running, and the hotfix's checks run at the same time.
- Nothing is billed for a batch that moved back. None of its checks had run. Merge lanes says what its rebuild costs in engine time.
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"
- A key is
fleet:<id>for an agent group,person:<login>oragent:<id>. The list takes at most 1,000 keys. agingis how long a normal task waits before it goes in with the priority lane. It is 5 minutes when left out and at most 7 days. A shortagingkeeps the normal lane moving while the priority lane is busy.
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.
by | The task has the lane because |
|---|---|
set | a project admin set it on the task |
rule | priority in the rules names the task's key |
stack | a task stacked on it is in that lane, so it must merge first |
Next
- Merge lanes: what each lane does to the order.
- Write rules and checks: weights and
agingin the[merge_queue]table. - How a task reaches main: why a submitted task waits.