# Review and approval In this guide you will read the review inbox, decide which changes merge by themselves and which wait for a person, approve a change or send it back, and see your decision in the merge record. Agents cannot approve; only people and the project's admin key can. ## What reaches the inbox When a task is submitted, every change in it is judged against the project's [rules](/rules). A change a rule lets merge once its checks pass does not wait for anyone. These wait in the inbox, each with the reasons it ranks where it does, the rule that matched, the risk, the paths and the symbols it touches: - a change a rule sends to a person, and a change no rule covers; - a change on paths a team owns, until that team has approved; - any change under `.yard/`, the rules and checks themselves; - every change, while the project has no checks at all: nothing merges unreviewed when nothing is tested; - a fix Switchyard made to a conflict, until a person approves it, unless the project lets fixes go straight in. A task whose key was issued with merge permission is the exception: it merges where a rule would otherwise send it to a person, which is what that permission is for. The board's inbox and `yard review` show the same list. A task held for review is not tested while it waits; its checks run once it is approved, and it merges when they pass. While a conflict fix waits for approval, or while merging is paused, the checks do run, so the person approving sees a failure beside the change rather than after. ## Approve, comment, or ask for a fix On the board, open the change from the inbox: its diff, its versions, the task's goal and plan, and the reasons. From the terminal: ```sh yard review yard review approve yard review request-fix -m "what needs fixing" yard review comment -m "a question" --at src/cart.ts:42 ``` `yard review` lists the inbox and the tasks waiting for review in the merge queue; `--interactive` asks what to do with each item, and `--verbose` shows every reason. A change is named by its short id, its `Change-Id` or any unique prefix. An approval is for one version of the change; if the agent pushes a new version, the new version waits again. A fix request is recorded on the change with your message, and the task stays submitted and held. The agent sees it in Switchyard's note on its next push and in its warnings, pushes a new version, and submits again; the new version waits for your approval. ## Who may review Owners, admins and members of the project's team review, signed in or with the admin key. A task key reads the inbox but cannot approve, not even its own change, and an agent group key cannot either. Where a team owns the paths, the rules may ask for more than one of its members, and the merge waits until that many have approved. On a project that follows a GitHub repository and shows its tasks as pull requests, an approval there from someone with write access to the repository counts as well. ## Turning review off, and letting fixes through Two project settings change how much waits: - **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. - **Fixes go straight in** lets a conflict fix Switchyard made merge without a person's approval. The default is that a person approves each one. Both are on the project's settings page and in the API (`PUT /reviews`, `PUT /fixes`), and both are recorded in the project's history. ## Your decision in the record Every merge has a signed merge record naming, for each change, the reviews that let it merge and the checks that passed. `yard verify ` prints it and checks the signature; the [guarantees](/guarantees) page says what the record promises. ## What you have now An inbox you can work from the board or the terminal, rules that decide what needs you, and a record of every approval. Next: the [rules and checks](/rules) guide, for the rules that keep the inbox short.