# Pull requests: review and merge

When a run finishes code work, it opens a pull request. Andon then reviews it, fixes what the review finds, waits for
CI, and merges it, as far as the team's level allows. This page says what happens on the way, and where you step in.

## The pipeline

A card with a pull request shows its pipeline on its face and in its history:

**Build** → **Review** (with the round number) → **CI** → **Merge**

How far Andon goes on its own depends on [how much Andon does](https://andon-docs.pages.dev/guide/autopilot.md):

| Level | Reviews | Merges | Moves the card to Done |
|---|---|---|---|
| **Manual** | no | no | no |
| **Assist** | yes | no: you merge | when the pull request merges |
| **Ship** | yes | yes, unless a guard rail holds it | yes |

## Review rounds

A review round reads the pull request in a fresh session, checks each card it covers, fixes what it can and pushes.
It posts what it found as a comment on the pull request. Rounds go on until the review is clean, or until the team's
**Review rounds before asking me**; then the pull request waits for you.

A finding the round can't settle by itself is **blocked**: a question for the card's owner. Answer it on the card:

| Answer | What happens |
|---|---|
| **Fix it** | The next round fixes it. Add how, if you like |
| **I handled it** | You fixed it yourself, outside the code: a database reset, a setting in a console |
| **Leave as is** | Nothing changes. Say why, if you like |
| **Follow-up card** | A new card for it, in the same project |

Failing CI checks get the same treatment: Andon fixes and pushes up to **CI fix attempts before asking me** times. At
0, a failing check waits for you.

### Steer the pipeline

The pipeline's bar on the card has its controls:

- **Pause** and **Resume** hold the pipeline while you decide.
- **Review again** starts another round.
- **Stop pipeline** ends it. The pull request stays open.
- **Resolve merge conflicts** starts a run that resolves them. If the card already has a run going, the run is
  queued (the bar reads *Resolving merge conflicts: queued*) and starts when that one finishes.

## Merge

With **Ship**, Andon merges once the review is clean, CI is green and GitHub allows it. The card moves to Done.

Andon doesn't merge, and the card shows **Ready to merge** in [Needs you](https://andon-docs.pages.dev/guide/needs-you.md), when:

- the pull request touches a path in **Never merge unattended**, or one of the standard paths while **Protect the
  standard paths** is on;
- the team is on **Assist**;
- the machine's local policy doesn't allow merging.

Then **Merge now** on the card, or on the pipeline's bar, merges it. When GitHub needs an approval first, the button
reads **Merge when approved**. Andon never merges past GitHub's own review rule.

## Change how pull requests are handled

For every team: **Settings → Automation**.

| Where | Setting |
|---|---|
| **How much Andon does** | the level |
| **Guard rails** | **Never merge unattended** (one path pattern a line), **Protect the standard paths** |
| **Advanced** | **Review rounds before asking me**, **CI fix attempts before asking me**, **Merge method** (**Squash**, **Merge commit** or **Rebase**), **Second reviewer** |

For one team, search Settings for the setting, such as **Auto review**, **Auto merge after review**, **Merge
method**, **Never auto-merge paths** or **Delete the branch after merging**, and pick the team. These are in the
team's **Pull requests** section, which isn't on its page (see [Where each setting is](https://andon-docs.pages.dev/guide/settings-map.md)).

A repository can set them too, in its `.andon/settings.json`. See
[Repository settings](https://andon-docs.pages.dev/reference/repo-settings.md).

## Ask a second reviewer

A second reviewer, usually a review bot, can look at each pull request after Andon's own review. Andon asks it, waits
for its review, and fixes what it asks for in another round.

### Turn it on

1. Open **Settings → Automation** and open **Advanced**.
2. In **Second reviewer**, pick how to ask:
   - **Ask with a comment** posts a comment on the pull request, such as `@review-bot review`.
   - **Add as a reviewer on GitHub** requests the reviewer on GitHub.
3. Type the reviewer's GitHub login in **Reviewer's GitHub login**, for example `review-bot` or `review-bot[bot]`.

For one team, search Settings for **Ask for another review** and pick the team. There you can also set **Review
request comment** and **Wait for the review at most (minutes)**, from 5 to 1440. The wait is 60 minutes unless you
change it.

### What happens on the pull request

Once Andon's review is clean, CI is green and every open review thread is handled:

1. **Ask.** The machine asks the reviewer. The pipeline says *Asked @review-bot to review* with the commit.
2. **Wait.** *Waiting for @review-bot to review* until its review of that commit arrives. With no review in time, the
   pipeline stops with *No review from @review-bot* and the pull request waits for you.
3. **Fix.** A review that asks for changes starts another round, which fixes what is right and in scope and pushes.
4. **Again.** The push is a new commit, so the reviewer is asked again, until it asks for nothing. Then the pipeline
   goes on to merge, or to **Ready to merge**.

**Merge now** skips the second reviewer: a person has looked at the pull request.
