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.
| Code | State | The check shows | What it means |
|---|---|---|---|
queued | queued | queued | In the merge queue, waiting its turn to be tested with main and the work ahead of it. |
testing | testing | in progress | Its checks are running with main and the work ahead of it, or it is being merged. |
merged | merged | success | Merged into main by the merge queue, after its checks passed with the work queued beside it. |
waiting_draft | waiting | in progress | A draft: it is queued once it is marked ready for review, as long as it keeps the label. |
waiting_review | waiting | in progress | Tested 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_requested | held | in progress | Someone asked for a fix, on GitHub or on the board; a push of a new version sends it back for review. |
held | held | in progress | Held 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_paused | held | in progress | Merging on main is paused; the merge queue keeps it and merges it when merging resumes. |
held_spending | held | in progress | The organization reached its spending limit; it is tested and merged when the limit is raised. No amount is ever shown on GitHub. |
held_github_unread | held | in progress | Held: 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_land | held | in progress | New 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_failed | sent back | failure | Sent back: a check failed with it added to main and the work ahead of it. Push a fix to try again. |
check_timed_out | sent back | failure | Sent 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. |
conflict | sent back | failure | Sent 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_back | sent back | failure | Sent back for the reason its sentence gives, such as rules it does not meet or a rules file that cannot be read. |
base_not_default | refused | action required | Not queued: it targets a branch other than main, and the merge queue lands work only on main. |
too_big | refused | action required | Not queued: it changes more than 4,096 files or 200,000 lines, more than one task takes. |
below_history | refused | action required | Not queued: it is based on a commit older than the history Switchyard has copied from GitHub. |
not_analysed | refused | action required | Not queued: Switchyard could not analyse its head. Add the label again to queue it. |
not_queued | refused | action required | Its new commits could not be put in the merge queue at the time they arrived. Push again, or add the label again. |
labeler_cannot_write | refused | action required | Not queued: the label came from someone without write access to the repository. |
new_commits_need_writer | withdrawn | neutral | Taken out: its author cannot write to the repository and pushed new commits, so someone with write access adds the label again. |
retargeted | withdrawn | neutral | Taken out: it now targets a branch other than main. |
withdrawn | withdrawn | neutral | Taken out: its task was abandoned in Switchyard, on the board, with yard or by an agent. |
withdrawn_label_removed | withdrawn | neutral | Taken out: the label was removed. Add it again to queue it. |
withdrawn_closed | withdrawn | neutral | Taken out: the pull request was closed without a merge. |
merged_on_github | withdrawn | neutral | Merged on GitHub before the merge queue merged it, so the merge queue let it go. |