# PR reviews

> Automatic pull request reviews and re-reviews, approval checks, and auto-merge.

Pullfrog reviews every new pull request and re-reviews each push. Configure reviews in the repository console under **Automations → Review PRs**.

## Auto-review new PRs

Pullfrog reviews a PR when it opens, or when a draft is marked ready for review. The first review opens with a one-line verdict on the PR's approach and a summary of the change, followed by inline feedback.

![A Pullfrog review with a summary, the Fix all and Fix 👍s links, and an inline comment carrying a suggested change](https://pullfrog.com/docs/images/pr-review-summary.png)

When Pullfrog disagrees with the approach, or with making the change at all, a section at the top of the review explains why. For a small fix, an inline comment carries a GitHub suggested change that you can commit from the thread. A review looks for defects by default, and [review instructions](https://pullfrog.com/docs/instructions#review-instructions) change its focus.

| Option | Default | Effect |
| --- | --- | --- |
| **Re-review when new commits are pushed** | On | Review each push incrementally ([below](https://pullfrog.com/docs/pr-reviews#re-review-on-new-commits)) |
| **Allow Pullfrog to approve PRs** | Off | Submit approvals and change requests. When off, every review is a comment. |
| **Review Pullfrog's own PRs** | Off | Review PRs that Pullfrog opened |
| **Include PRs from external contributors** | On | Review PRs from non-collaborators. Public repositories only. |
| **Include draft PRs** | Off | Review and re-review draft PRs |
| **Include PRs opened by bots** | Off | Review PRs from Dependabot, Renovate, Greenkeeper, Snyk, and `github-actions[bot]`, and changesets release PRs |
| **Limit reviews to target branches** | Any branch | Review only PRs into the branches you pick ([Base branches](https://pullfrog.com/docs/pr-reviews#base-branches)) |
| **Skip PRs and pushes from** | Nobody | Accounts whose PRs and pushes start no automatic review ([Skipped accounts](https://pullfrog.com/docs/pr-reviews#skipped-accounts)) |

A repository that limits reviews to users with explicit access makes GitHub refuse Pullfrog's approvals and change requests. They post as comments and never arm auto-merge.

> GitHub attributes a PR opened by any of your workflows to `github-actions[bot]`. Release PRs from release-please, git-pr-release, or a custom script are skipped until **Include PRs opened by bots** is on.

To review a PR the automation skips, mention `@pullfrog` in a comment on it.

## Re-review on new commits

When new commits land on a PR that Pullfrog already reviewed, it reviews only the new changes. The re-review summarizes what changed since the previous review, so the PR keeps a running record.

If a review is still running when more commits arrive, that run covers them and no second run starts.

### Skipped pushes

A push starts no re-review when every commit since Pullfrog's last review carries one of GitHub's [skip instructions](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs), such as `[skip ci]` in the commit message.

- A push that mixes marked and unmarked commits is re-reviewed, marked commits included.
- The next re-review covers any marked commits skipped before it.
- The skipped head gets no `pullfrog` or `pullfrog-approval` check, and an approval the push dismissed is not renewed. A required check or approval waits for your next push.

### Approvals after a push

With **Allow Pullfrog to approve PRs** on, a re-review keeps the PR approved.

- A push can dismiss Pullfrog's approval, as GitHub's **Dismiss stale pull request approvals when new commits are pushed** rule does. The re-review approves again even if the new commits need no review, such as a base-branch merge that resolved a conflict.
- Pullfrog's own pushes count too, such as a fix for review feedback or a failing check.
- Resolving the last open Pullfrog review thread starts a re-review, so a finding settled in discussion gets an approval without a code change. The person resolving it needs write access to the repository.

## Base branches

Pullfrog reviews PRs into any branch by default. **Limit reviews to target branches** narrows that to branches you pick from the repository's own list, which shows the default branch first and then the most recently updated ones.

A team that merges feature branches into `develop` and cuts release PRs into `main` can pick `develop`. The release PR then goes unreviewed, since its changes were reviewed on the way in.

> The setting scopes the review on open and the re-review on push. An `@pullfrog` mention, addressing reviews, and fixing CI failures work on a PR into any branch.

## Skipped accounts

**Skip PRs and pushes from** takes GitHub logins separated by commas, such as `release-bot[bot], fixup-agent[bot]`. The `[bot]` suffix is optional.

- A PR one of them opens gets no automatic review or re-review.
- A push one of them makes to any PR starts no re-review. The next re-review covers everything since Pullfrog's last review, so it includes their commits.

Use it for automation whose output needs no review of its own, such as an internal release bot or an agent that pushes fix-up commits to PRs people opened. **Include PRs opened by bots** covers a fixed list of dependency bots; this option takes any account.

## Auto-merge approved PRs

With auto-merge on, a PR that Pullfrog approves goes to GitHub's native auto-merge. GitHub merges it once your required status checks pass and any required reviews are in.

Auto-merge is experimental. It needs all of the following:

- **Auto-merge approved PRs** turned on in the **Review PRs** card. Only a repository admin can turn it on, and the console asks you to type `MERGE` to confirm.
- **Allow Pullfrog to approve PRs** turned on.
- Branch protection on the base branch with at least one required status check. Without it, Pullfrog approves, does not merge, and comments to say so.
- **Allow auto-merge** turned on in the repository's GitHub settings (**Settings → General → Pull Requests**). It is off by default.

Branch protection decides what holds a merge back:

- Pullfrog never merges past a check or review that branch protection requires. Checks that aren't required don't hold the merge back, so mark a check as required if it must pass.
- Auto-merge covers every PR Pullfrog approves, including PRs from contributors and forks. A fork cannot fake a required check, so a contributor's code still has to pass your CI.
- A person's "Request changes" review blocks the merge until it is resolved. Add a required human reviewer to branch protection if a person must sign off on every merge.

## Status checks

Pullfrog dispatches its GitHub Actions runs against your default branch, so the run never appears in a PR's checks list. Two checks put Pullfrog's state on the PR instead, each a toggle in the **Review PRs** card.

| Check | Default | Reports | Console toggle |
| --- | --- | --- | --- |
| `pullfrog` | On | Whether a Pullfrog run is in progress, succeeded, or failed | **Add Pullfrog's run status as a Check on pull requests** |
| `pullfrog-approval` | Off | Whether Pullfrog would approve the PR | **Add Pullfrog's approval verdict as a Check on pull requests** |

Neither check blocks a merge until you add it to the branch's required status checks in GitHub. The deprecated `status_checks: enabled` workflow input still posts both checks whatever the toggles say, so remove it from your workflow.

![The pullfrog check passing in a pull request's merge box](https://pullfrog.com/docs/images/pr-status-checks.png)

### `pullfrog`

The check appears on the PR head as soon as a run is dispatched, before the runner starts, and shows **Pullfrog is running**. When the run ends, it resolves to success, or to failure, cancelled, or timed out with a link to the run logs.

### `pullfrog-approval`

The check succeeds when Pullfrog has no outstanding feedback. It fails when Pullfrog requested changes or when any earlier Pullfrog review thread is still unresolved, even if the latest commit introduces no new issue.

- It is independent of **Allow Pullfrog to approve PRs**, so you can require the check without letting Pullfrog submit approvals.
- It attaches to the exact commit Pullfrog reviewed, and only runs that produce a review verdict post it. A new push has no `pullfrog-approval` check until Pullfrog re-reviews it, so a required check keeps the merge blocked until then.
- A re-review that finds nothing new to review, such as after a merge of the base branch, carries the previous verdict forward to the new head. A previous rejection carries forward after any re-review that submits no review.
- A run that fails or is cancelled posts no check, which also blocks the merge until the next run reports.
