# Checks on commits

> Read each run as a check on the commit, and require it before merging.

Source: https://rehearsal.dev/docs/github/checks

Each run a [rule](https://rehearsal.dev/docs/github/rules.md) starts reports as a check on the commit in GitHub. The check follows the run from queued to finished and links to the run in Rehearsal.

## The check's name

- A pull request rule reports as `Rehearsal`.
- A branch or pattern rule adds its branch, such as `Rehearsal · main` or `Rehearsal · release/*`.

The name comes from the rule, so you can require it by name in GitHub. A branch rule that moves to another branch reports under the new name.

## What a check says

| The run | The check's title | Conclusion |
| --- | --- | --- |
| Passed | 2 tests passed | `success` |
| A test failed | 1 of 2 tests failed: Check out a cart | `failure` |
| A test needs review | The page changed. Someone needs to accept it. | `failure` |
| Tests could not run | 1 of 2 tests could not run, or the reason | `action_required` |
| Cancelled | This run was cancelled | `cancelled` |
| Rehearsal could not run it | Could not run these tests. You were not charged. | `action_required` |

Only a passing run ends as `success`. A run that could not finish never counts as a pass, so a required check stays blocked.

Below the title, the check says what to do next and which address it tested. Then it lists each test with its result and time, and links to the run:

```text
Open the run to see where each test stopped.

Tested https://parcel-git-fix-cart.vercel.app

Test                   Result   Time
Check out a cart       Failed   22s
Apply a discount code  Passed   17s

See the run
```

| Result | What it means |
| --- | --- |
| Passed | The test passed. |
| Failed | The test stopped at a step. The run shows which one and what the page showed. |
| Page changed | The page changed under the test. Someone with access accepts the change, then runs the tests again. |
| Could not run | The test was blocked before it could finish. |
| Cancelled | The run stopped before this test finished. |
| Not ready | The test was not ready when the run started, so it was not checked. |

**See the run** opens the run in Rehearsal, where you can watch the recording. It needs a Rehearsal sign-in. The check carries no other link.

A check with a fixed address adds that it could not verify the deployed commit. A check can also end before any test runs. [Preview deployments](https://rehearsal.dev/docs/github/preview-deployments.md) lists those endings.

## Runs we could not finish

Sometimes a run stops because of a problem on our side. Its check ends as `action_required` and says you were not charged. The run does not count towards your plan. Re-run the check when you are ready.

See [Runs we could not finish](https://rehearsal.dev/docs/billing/runs-we-could-not-finish.md).

## Run a check again

Re-run a Rehearsal check in GitHub, and Rehearsal runs the same tests again on the same commit, at the same versions and address. The new run gets a check of its own.

- The earlier run has to be finished. A check still waiting for a deployment has nothing to run again.
- Re-running every check on a commit runs each Rehearsal check on it again.
- A new run counts towards your plan, like any other run.

## Require the check before merging

1. **Ask for it in the rule**

   In a pull request rule, turn on **Require passing tests before merging** and save the rule.

2. **Require the check in GitHub**

   - Open the repository's settings in GitHub.
   - Open **Rules** and choose the rule for your target branch.
   - Require status checks and add `Rehearsal`.

3. **Let Rehearsal read it back**

   In the rule, press **Check now**. Rehearsal reads GitHub's rules for the branch. When GitHub requires the check, the rule says **GitHub requires the Rehearsal check.**

> [!NOTE]
> Until Rehearsal has read it, the rule says **Merging is not blocked yet.** The rule's sentence only mentions merging once GitHub confirms it.

A GitHub rule that ties the check to a different app does not count.

## Every check in Rehearsal

**Deployments** in the sidebar lists the runs your rules started, grouped by pull request and by branch. A pull request still waiting for its preview reads **Waiting for a deployment**. Each run's menu has **Open the check on GitHub**.

## Next steps

- Test each pull request's [Vercel preview](https://rehearsal.dev/docs/github/preview-deployments.md).
- Run the same tests from your terminal with the [CLI](https://rehearsal.dev/docs/cli/run-tests.md).