switchyard

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

Reason codes

Where a pull request or a task stands in the merge queue is said twice: in a sentence for people, and in a stable reason code for scripts and agents. The code is in the status comment's first line, in the switchyard queue check's details, in GET /pulls/{number}, in yard pr status --json and in the MCP tool yard_pr_status, and in a task's mergeQueue.code. Match on the code, never on the sentence: the words may change, the codes do not. This page is rendered from the list the server uses, so it holds every code Switchyard emits and no other.

Each code belongs to a state, and the state sets what the switchyard queue check shows on the pull request's head. The check is never one to require in branch protection: require switchyard instead, as Pull requests explains.

CodeStateThe check showsWhat it means
queuedqueuedqueuedIn the merge queue, waiting its turn to be tested with main and the work ahead of it.
testingtestingin progressIts checks are running with main and the work ahead of it, or it is being merged.
mergedmergedsuccessMerged into main by the merge queue, after its checks passed with the work queued beside it.
waiting_draftwaitingin progressA draft: it is queued once it is marked ready for review, as long as it keeps the label.
waiting_reviewwaitingin progressTested or waiting its turn, and held until a person approves it: a review the project's rules ask for, or GitHub's rules on main (approvals, code owners, the latest push).
changes_requestedheldin progressSomeone asked for a fix, on GitHub or on the board; a push of a new version sends it back for review.
heldheldin progressHeld in the merge queue for the reason its sentence gives, such as main's own checks failing or a check that could not run.
held_pausedheldin progressMerging on main is paused; the merge queue keeps it and merges it when merging resumes.
held_spendingheldin progressThe organization reached its spending limit; it is tested and merged when the limit is raised. No amount is ever shown on GitHub.
held_github_unreadheldin progressHeld: GitHub could not say whether it meets the rules on main (a part of the pull request it did not give, no review decision where main's ruleset asks reviews, or more review conversations than Switchyard reads). The merge queue asks again, and never lands it on a guess.
held_agents_may_not_landheldin progressNew commits were pushed by an agent, and the organization lets no agent land work, so a person on the team submits them on the board.
check_failedsent backfailureSent back: a check failed with it added to main and the work ahead of it. Push a fix to try again.
check_timed_outsent backfailureSent back: a check ran past its time limit with it added to main and the work ahead of it. Push a fix to try again.
conflictsent backfailureSent back: it conflicts with main and could not be merged with the work ahead of it. Bring main in, fix the conflict and push.
sent_backsent backfailureSent back for the reason its sentence gives, such as rules it does not meet or a rules file that cannot be read.
base_not_defaultrefusedaction requiredNot queued: it targets a branch other than main, and the merge queue lands work only on main.
too_bigrefusedaction requiredNot queued: it changes more than 4,096 files or 200,000 lines, more than one task takes.
below_historyrefusedaction requiredNot queued: it is based on a commit older than the history Switchyard has copied from GitHub.
not_analysedrefusedaction requiredNot queued: Switchyard could not analyse its head. Add the label again to queue it.
not_queuedrefusedaction requiredIts new commits could not be put in the merge queue at the time they arrived. Push again, or add the label again.
labeler_cannot_writerefusedaction requiredNot queued: the label came from someone without write access to the repository.
new_commits_need_writerwithdrawnneutralTaken out: its author cannot write to the repository and pushed new commits, so someone with write access adds the label again.
retargetedwithdrawnneutralTaken out: it now targets a branch other than main.
withdrawnwithdrawnneutralTaken out: its task was abandoned in Switchyard, on the board, with yard or by an agent.
withdrawn_label_removedwithdrawnneutralTaken out: the label was removed. Add it again to queue it.
withdrawn_closedwithdrawnneutralTaken out: the pull request was closed without a merge.
merged_on_githubwithdrawnneutralMerged on GitHub before the merge queue merged it, so the merge queue let it go.