# GitHub pull requests

This guide shows what a Flow code review does on a pull request on GitHub. You will learn:

- What the review posts, and how the "Flow review" check reads
- Each state of the check, and what to do about it
- The comments that start a review again

## Overview

Each pull request gets a review when it opens, and each push gets a review of its new commits. The review posts one comment for each finding, on the changed line. A comment gives the severity, the lenses, the finding, its impact and the fix. Some comments also have a suggested change that you can commit from GitHub.

When a later push fixes a finding, the review replies "Addressed in" with the commit, and resolves the comment.

## The Flow review check

Each review has a check named "Flow review" in the checks of the pull request. Its title counts the open findings by severity. Its summary says if a critical or major finding is open, names the agent and the model, lists the tasks of the review, and links to the logs of the run.

::figure
![The Flow review check on GitHub: the title "1 minor open", the summary, the task list of twelve tasks and the link to the run logs](/images/docs/reviews/flow-review-check.png)
::

The check fails while a critical or major finding is open. To block the merge of such a pull request, make "Flow review" a required check in the branch protection or the ruleset of your default branch.

## The states of the check

Each state is the title of the check, with its result on GitHub.

::::field-group
:::field{name="Reviewing" type="in progress"}
The review runs, and the title counts the tasks that are done. A review takes a few minutes.
:::

:::field{name="no open findings" type="success"}
The review ended, and no finding is open.
:::

:::field{name="2 minor open" type="success"}
The review ended. The open findings are minor or nits, so the check passes. Read the comments, and fix what you agree with.
:::

:::field{name="1 critical, 1 major open" type="failure"}
The review ended, and a critical or major finding is open. Fix the findings, or accept them. See [Accepting a finding](/docs/flow/reviews/configuration#accepting-a-finding).
:::

:::field{name="Waiting" type="queued"}
You pushed while an earlier push was under review. This push waits for that review to end, and its review then starts on its own.
:::

:::field{name="Superseded" type="skipped"}
A newer push came while this one waited. The newer push gets the review.
:::

:::field{name="Not reviewed" type="skipped"}
The pull request was closed before its review started. Reopen it to get a review.
:::

:::field{name="The review did not finish" type="neutral"}
The run stopped before it posted the findings. A neutral check does not block the merge. Re-run the check, or comment `@adonisjs-flow full review`.
:::

:::field{name="The review did not start" type="failure"}
The workflow failed before the review, for example because a secret is missing. The summary names the cause. Fix it, then re-run the check. "The review stopped" is the same failure after the review started.
:::

:::field{name="The Flow review workflow is missing" type="neutral"}
The default branch has no `.github/workflows/flow-review.yml`. Merge the setup pull request. See [GitHub setup](/docs/flow/reviews/setup).
:::

:::field{name="This account has no Flow licence" type="neutral"}
The installation of the GitHub App is not connected to a Plus membership, or the membership ended. Connect the installation in your [dashboard](/account), or renew your membership.
:::

:::field{name="Flow couldn't confirm the licence. Re-run the review." type="neutral"}
Plus did not answer in time. Re-run the check.
:::
::::

## Comments that start a review

Comment on the pull request, with the command as the first line of the comment. Only people with write access to the repository can ask. Flow reacts with 👍 when it takes the request. When it refuses one, it reacts with 👎 and replies with the reason.

### Review every change again

After the first review, each push gets a review of its new commits only. To review the whole pull request again, for example after a rebase, after you change the settings or the lenses, or after a review that did not finish, comment:

```txt
@adonisjs-flow full review
```

### See every finding

A review reports at most `maxFindings` findings, the most severe first. To review every change again and report each finding, comment:

```txt
@adonisjs-flow full review all
```

### Review a new push

You need no comment. Each push gets its review on its own.

### Accept a finding

You need no comment either. Add the finding to `accepted` in `.flow/review.yml`, or write a `flow-allow` comment above the code. See [Accepting a finding](/docs/flow/reviews/configuration#accepting-a-finding).

## Next steps

::card-group
:::card{title="Local reviews" to="/docs/flow/reviews/local-reviews"}
Review your branch on your computer, and write an HTML report.
:::

:::card{title="Configuration" to="/docs/flow/reviews/configuration"}
The settings of the review, and accepting a finding.
:::
::
