switchyard

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

Review a change

Read the review inbox and approve a change, comment on it, or ask for a fix, so that the merge queue can merge it.

You will have: a decision on each change that waits for you, and that decision in the signed merge record. Works with: the board, yard, MCP (yard_review), REST. An approval needs a person signed in.

Only a person signed in approves. No key approves: not a task key, an agent group key, an organization API key or the project admin key. The rules decide which changes wait for a person.

Prerequisites

Step 1 — Read the inbox

Run yard review. It lists the change versions of submitted tasks and the tasks that the merge queue holds for review, with why each one waits. On a terminal, yard review asks what to do with each item. --interactive asks also when the input is not a terminal. --verbose shows every reason.

On the board, the inbox (needs you) shows the same. A change opens to its diff, its versions, the task's goal and plan, and the reasons.

When a task is submitted, the merge queue judges every change in it against the rules. A change that a rule lets merge once its checks pass waits for nobody. The inbox labels it review optional, and an early approval still counts. These changes wait for a person:

A task whose key was made with merge permission merges where an ordinary rule would send it to a person. The permission never clears a protected rule, an owned path or a change under .yard/.

While a task waits for review, the merge queue runs its checks when it is otherwise idle, so that an approval can merge at once. yard settings set checks-while-reviewing off makes a task wait for its approval before its checks run.

You know what waits for you. Next, you decide.

Step 2 — Approve, comment, or ask for a fix

Name a change by its short id, its Change-Id or any unique prefix of it.

yard review approve <change>
yard review request-fix <change> -m "what needs fixing"
yard review comment <change> -m "a question" --at src/cart.ts:42

On the board, the same three actions are on the change.

Warning: on app.switchyard.so an approval made from the terminal or by an agent is not final until you confirm it in a browser where you signed in within the last 15 minutes. yard review approve <change> prints why it waits and the link, and exits 8. yard review approve <change> --wait waits until you confirm. Where your organization lets agents approve work, an approval of another person's unprotected change counts at once (What needs a browser click).

Your decision is recorded. Next, you watch the task.

Step 3 — Watch the task

An approval is for one version of a change. When the agent pushes a new version, the new version waits again.

A fix request keeps the task submitted and held. The task's merge queue reason says task 3 waits for a fix:, names who asked and your message, and ends push a new version of that change and it goes back for review. The agent reads it in yard status and in Switchyard's note on its MCP answers.

Who may approve

Owners, admins, developers and members of the project's organization approve.

A protected change needs a person other than the task's people: who started it, its assignee, who pushed to it and who wrote its commits. yard settings set self-approval on lets them approve their own. Where a team owns the paths, the merge waits until as many of its members have approved as the rules ask. Approvals by the task's own people count for no team.

On a project that follows a GitHub repository, an approval on a pull request that Switchyard took into the merge queue counts too. It must come from someone with admin, maintain or write access to the repository, on the pull request's current head, and not from its author. A bot's approval never counts, and a protected change still needs a person on the project's team. Changes requested on GitHub counts as a fix request.

A pull request that an app on the project's list pushed or opened is that app's own change, which any one person may approve. The list is dependabot[bot] and renovate[bot] by default, and yard settings set allowed-apps changes it. github-actions[bot] is never on the list.

Turn review off, or let fixes through

Two project settings change how much waits. The project's history records each change, and both are on the project's settings page too.

  1. yard settings set reviews off adds a last rule that lets every change no rule covers merge once its checks pass. Rules that ask for a person still apply, and so do the holds for .yard/ and for GitHub's workflow files.
  2. yard settings set fixes auto lets a conflict fix Switchyard made merge without a person's approval. approve, the default, sends each one to the inbox.

Warning: on hosted Switchyard, reviews off, fixes auto, self-approval on and adding an app to allowed-apps loosen a review gate. Only a person signed in in a browser within the last 15 minutes changes them, on the settings page. A key or a yard sign-in is refused with loosens a review gate, so a person signed in does it in a browser, within the last 15 minutes: the settings page. Any key may tighten a gate.

Verify

Run yard verify <commit> on the merged commit. It prints the signed merge record and checks its signature. For each change, the record says who approved it, or that the rules or the task's merge permission let it merge, and it names the checks that passed. The guarantees page says what the record promises.

Next