> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/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](/docs/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](/docs/concepts#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.

```sh
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](/docs/concepts#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.

```sh
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](/docs/rules#share-the-merge-queue-fairly). Every task of those keys goes in the priority lane when it is submitted, with no command.

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

- A key is `fleet:<id>` for an agent group, `person:<login>` or `agent:<id>`. The list takes at most 1,000 keys.
- `aging` is 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 short `aging` keeps 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

```sh
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](/docs/undo) 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](/docs/concepts#merge-lanes): what each lane does to the order.
- [Write rules and checks](/docs/rules#share-the-merge-queue-fairly): weights and `aging` in the `[merge_queue]` table.
- [How a task reaches main](/docs/task-lifecycle): why a submitted task waits.
