switchyard

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

Pull requests in the merge queue

A pull request on the followed repository can go through the merge queue like any task. A person's branch or a bot's branch is then tested beside the agents' work, and merged when its checks pass. On GitHub, the pull request is what you work with. Inside Switchyard, it becomes one task, and the board, yard and the API show that task.

The pull request shows where it stands in two places. One status comment is made once and then edited in place. One check, switchyard queue, is on its head. Both say the same thing, in a sentence for people and in a reason code for scripts and agents.

Before you start

Put a pull request in the merge queue

  1. Add the label switchyard to the pull request. The label must come from someone with write access to the repository. A label from someone without write access is not acted on, and the status comment says why. A label from a bot is ignored. The queue_label key in the [github] table of the rules file changes the label's name.
  2. Switchyard makes a task named PR #<number>: <title>, imports the pull request's head and submits it. The status comment says it is in the merge queue.
  3. The task goes through the merge queue like any other task: checks, review rules and the merge with main. When it merges, the status comment names the commit on main, and Switchyard closes the pull request. Before the close, Switchyard adds the label externally-merged to the pull request, best effort, so that a tracker such as Linear counts it as merged. When it is sent back, the status comment gives the reason, and the pull request's author gets one short comment that points to it.
  4. To try again, push new commits to the branch. A push replaces the task's head and submits it again. When the pull request's author cannot write to the repository, a new push takes the task out of the merge queue and removes the label. Someone with write access then adds the label again.
  5. To take the pull request out, remove the label or close the pull request. The task is abandoned, and the status comment says so.

A draft is queued when it is marked ready for review, as long as it keeps the label. A pull request that goes back to draft, or that is pointed at a branch other than main, leaves the merge queue.

A task can name the issue it serves in Linear, Jira or GitHub Issues: Use Switchyard with GitHub Issues has the steps, and Linear and Jira each have a guide.

An approval or a request for changes on the tested head counts as that person's review when the person has admin, maintain or write access. A bot's approval and the author's own approval never count. Review a change says who may approve a protected change.

Switchyard does not queue some pull requests, and the status comment says why:

While the organization is at its spending limit, a labelled pull request is taken and held. The status comment says so and names no amount.

The status comment

Switchyard makes one comment on the pull request the first time it has something to say, and edits that comment each time the pull request's state changes. The comment is not edited when nothing changed, so a busy merge queue does not fill the pull request's history. When a person deletes the comment, the next change makes it again.

The comment has three parts:

A send-back also gets one short comment of its own, which mentions the pull request's author, so that GitHub notifies them: Sent back: <code>. Details in the status comment above. Each send-back gets one such comment, never more.

Output quoted from a failed check has anything that looks like a secret removed before it is shown on the pull request.

The check on your pull request

While the merge queue has the pull request, its head carries a check named switchyard queue. The check is in progress while the pull request waits or is tested, and ends when the merge queue is done with it:

StateThe check shows
queuedqueued
testing, waiting, heldin progress
mergedsuccess
sent backfailure
not queuedaction required
taken outneutral

The check's title says the state in a few words. Its details hold the sentence, the reason code and its meaning, and a block of JSON with the code, the state, the task, the head and the lane. When new commits arrive, the check on the old head ends as neutral, titled Superseded by <commit>, and the new head gets a check of its own.

Never require switchyard queue in a ruleset or in branch protection. It says where the pull request is in the merge queue, not whether the work passed it: a pull request taken out of the queue ends it as neutral, and one that was not queued ends it as action required. GitHub counts a neutral check as passed, so a rule requiring switchyard queue would let a pull request that was taken out of the merge queue merge. Switchyard does not warn about such a rule, so check your rulesets and branch protection yourself. To require that work passed the merge queue, require the check switchyard, with its source set to the Switchyard app, as When main is protected shows. That check is set on the commit that landed on main, after the merge queue tested it.

When the Switchyard App may not write checks on the repository, the status comment is still written, and Switchyard asks for the checks again an hour later.

Read the state from a script or an agent

The same state, with the same reason code, is in three places:

The answer carries state, code, reason (the sentence), task, head, lane and position in line. Match on code, never on reason: the sentences may change, and the codes do not. Reason codes lists every code.

Rate limits

Switchyard writes to a pull request only when its reason code or its head changes, and writes the status of a project's pull requests at most 30 times a minute and 300 times an hour, which keeps it well under GitHub's limits on writes. When there is more to write, the outcomes (merged, sent back, not queued, taken out) are written first, and the rest are written in the next minutes. When GitHub asks Switchyard to slow down, Switchyard waits for as long as GitHub asked before it writes to any pull request of the project again, and then writes the latest state. The state is kept while it waits, so no state is lost. When GitHub's answer to a new status comment or check is lost on the way, Switchyard looks for the one it made before it makes another, so it is not made a second time.

Next