> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Approvals and merge controls

> Choose an autonomy level, clear plan and PR gates, and control when the Factory can merge.

**Passing a gate is not the same as merging.** `plan-ok` lets building begin. `pr-ok` is a
per-PR approval checkpoint. Land checks whether the Factory is authorized to merge the current PR.

## Choose an autonomy level

| `policy.autonomy` | Plan OK | PR OK |
| - | - | - |
| `calibrating` (default) | Required | Every PR |
| `standard` | Required | Protected changes only |
| `autonomous` | Still required in the standard Factory pipeline | Protected changes only |

`autonomous` does not remove `plan-ok` in the shipped pipeline. The optional fast lane is a
separate path: a person-applied [`labels.fastLane`](https://docs.mutagent.io/factory/reference/factory-yaml#labels) can
preauthorize an eligible small, single-part plan outside protected paths. Review, PR approval rules
and holds still apply.

For example, require PR approval for changes to authentication or migrations. Merge these keys
into your existing [Factory file](https://docs.mutagent.io/factory/reference/factory-yaml.md):

```yaml theme={null}
policy:
  autonomy: standard
  merge: { preset: as-ready }
  review: { maxLoops: 3 }
repos:
  - name: acme/web
    defaultBranch: main
    zones:
      protected: ['src/auth/**', 'db/migrations/**']
```

If the changed files can't be read and the repository has protected globs, the Factory treats the
change as protected. This setting is a Factory gate, not a replacement for GitHub branch protection.

## Approve or revise a plan

> [tab] GitHub
>
> 1. Read the published plan on the issue.
> 2. Add `factory:approved` to approve, or comment with what needs to change and add `factory:changes`.
> 3. For revisions, read the replacement plan and approve that plan. Follow the approval instruction
>    posted with it rather than relying on an earlier approval.
>
> The Factory consumes the plan labels. A card move isn't approval. A bare `/approve` comment is a
> legacy alias for an unchanged plan; it isn't required.

> [tab] CLI
>
> Use the full run ID. Run only the command for the decision you intend:
>
> ```bash theme={null}
> architech factory runs approve "$RUN_ID" --gate plan --json
> architech factory runs approve "$RUN_ID" --gate plan --request-changes "Include a rollback step" --json
> architech factory runs approve "$RUN_ID" --gate plan --reject --note "Do not proceed" --json
> ```
>
> Requesting changes re-plans in the same run; rejecting cancels it.

## Approve or send back a PR

In GitHub use **Review changes → Approve** for the PR you reviewed. Use **Request changes** with a
note to send it back to build. If GitHub doesn't let you review a PR you authored, apply the
configured `labels.approve` label (`merge:ready` by default), or use the CLI. For a board event
that reaches the Factory, a valid approval label can also count when it is already on the PR as the
gate opens. After a send-back, review and approve the changed work again.

```bash theme={null}
architech factory runs approve "$RUN_ID" --gate pr --sub-item "$SUB_ITEM" --json
architech factory runs approve "$RUN_ID" --gate pr --sub-item "$SUB_ITEM" --reject --note "Keep the public API unchanged" --json
```

Omitting `--sub-item` targets all waiting PR gates. Copy the specific command from the Inbox to
affect just one. An ordinary PR comment does not replace a GitHub review or the CLI decision.

### Who can decide?

* **GitHub approval and changes labels:** a person account with write, maintain or admin access,
  applied directly, not by or through a GitHub App. The Factory verifies who last applied the
  label and that it is still present. Use the names pinned to the run; yours may differ from the defaults.
* **GitHub reviews:** a person with write access to the PR's repository. GitHub does not let an
  author approve their own PR. A Cloud Factory review is independent evidence, not your approval.
* **CLI/API:** Mutagent workspace update permission, not GitHub repository permission.
* **Hold:** anyone's hold counts. Pickup is not a person-only approval; the Factory ignores its
  own pickup signals. CI and origin labels are not gate decisions.

## Stop or allow land

> [!WARNING]
>
> To stop the **Factory's** merge, add `merge:hold` to the PR, parent issue or sub-item. Remove all
> applicable holds to release it. Removing approval alone is not a reliable stop. The label does
> not prevent someone with permission from merging directly on GitHub.

```bash theme={null}
gh pr edit "$PR_NUMBER" --repo acme/web --add-label merge:hold
```

At land, a hold takes precedence over every merge preset and label:

* **`as-ready` (default):** land can squash-merge an `APPROVE` or `WATCH` review on the current
  head with green CI on that head. If the Factory verified there was no CI configured at review
  time, it can also accept no CI at land. An unread check is not a green check.
* **`standard` merge preset and other names:** ordinary review evidence alone does not authorize
  land. Apply the configured approval or loosen label. This preset is separate from `standard` autonomy.
* **Person-applied `merge:ready` or `merge:yolo`:** these labels can authorize land without the
  ordinary `as-ready` evidence. `merge:ready` can also pass `pr-ok`; `merge:yolo` is not a substitute
  for a pending PR gate. Neither overrides a hold, a stale head or GitHub's own merge rules.

For a protected change, an eligible native GitHub approval on the exact head can also authorize
land when the Factory can reverify the approval, protected scope, current base and green CI.
If you merge on GitHub while `pr-ok` waits, the Factory can record the observed merge and your
approval instead of merging twice. An App's merge or a merge under a hold is not person approval.

A new head invalidates old review and CI evidence. Removing the approval label removes its label
authority, not the fact that the PR gate passed; `as-ready` can still merge on evidence. Use a hold
for a veto, or submit **Request changes** for rework.

## When review runs out of rounds

`policy.review.maxLoops` is the send-back allowance per sub-item (default **2**, valid **1–10**).
It counts send-backs, not the initial review. Some automatic base refreshes are handled separately.
When review needs a further round, read the escalation and choose one of the offered options.

```bash theme={null}
architech factory escalations answer "$ESCALATION_ID" "Send it back for one more round" --json
```

The other options are **Approve it as it is** and **Cancel the run**. The first passes the stopped
stage; it doesn't make GitHub merge rules or other Factory controls disappear.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.