# Preview deployments

> Test the Vercel preview of each pull request and see the result on the commit.

Source: https://rehearsal.dev/docs/github/preview-deployments

A pull request rule can test the preview Vercel builds for each pull request. The result appears as a check on the pull request, so you see it before you merge.

Rehearsal learns about a preview from GitHub. Vercel reports each deployment there when your repository deploys through Vercel's GitHub integration.

## Set it up

1. **Connect the repository**

   Connect the repository Vercel deploys to your project. See [Connect a repository](https://rehearsal.dev/docs/github/connect-a-repository.md).

2. **Add a pull request rule**

   Open **Deployments**, press **Rules**, then **Add a rule**. Choose **When a pull request is opened or updated** and write the target branch, such as `main`.

3. **Choose the tests and the preview**

   Pick a suite or **All approved tests**. Under the address question, choose **The pull request's Vercel preview**. Press **Save rule**.

## On each pull request

1. **The pull request opens or changes**

   A check named `Rehearsal` appears on the newest commit. It reads "Waiting for Vercel to deploy this commit".

2. **The preview is ready**

   When Vercel reports the preview ready, the tests start against its address. The check reads "Queued" and then "Running", with the number of tests.

3. **The run ends**

   The check shows the result, a table of the tests and a link to the run. See [Checks on commits](https://rehearsal.dev/docs/github/checks.md).

## When no tests run

A waiting check always ends, so a required check never waits forever.

| What happened | The check reads | Conclusion |
| --- | --- | --- |
| The deployment failed | The deployment failed, so there was nothing to test | `action_required` |
| No deployment arrived within 30 minutes | Rehearsal did not receive a deployment for this commit | `timed_out` |
| A newer commit arrived | A newer commit replaced this one | `cancelled` |
| The pull request was closed | The pull request was closed | `cancelled` |

- Before a check closes for lack of a deployment, Rehearsal asks GitHub once whether it missed one. If it did, the tests run.
- A newer commit also stops a run that is still testing an older one.
- Failed and missing deployments end as `action_required` and `timed_out`, so a required check keeps the pull request from merging.

## Protected previews

Rehearsal cannot open protected previews yet, so your previews must be public.

The rule has a field for the secret from Vercel's **Protection Bypass for Automation**. You can save one there, but runs do not send it yet.

## Pull requests from forks

A pull request from a fork gets no check. Rehearsal skips it.

## Branch deployments

A branch or pattern rule can test **Vercel's deployment of the branch** instead, such as each deployment of `main`. It has no waiting check. The check appears when the tests start, under a name such as `Rehearsal · main`.

## Next steps

- [Require the check](https://rehearsal.dev/docs/github/checks.md) before a pull request can merge.
- See every option in [Rules for pull requests and deployments](https://rehearsal.dev/docs/github/rules.md).