Preview deployments

Test the Vercel preview of each pull request and see the result on the pull request before you merge.

If Vercel deploys a preview of every pull request, Rehearsal can test each preview as soon as it is ready and post the result on the pull request, so you know before you merge. This page sets up a rule that runs Parcel's release suite on the preview of every pull request into main, then follows one pull request through it.

Rehearsal hears about a preview from GitHub rather than from Vercel. When your project deploys through Vercel's GitHub integration, Vercel reports each deployment and its address to GitHub, and that report is what starts the tests.

Set it up Link to Set it up

  1. Step 1: Connect the repository

    Connect the repository that Vercel deploys to your project, as Connect a repository shows.

  2. Step 2: Add a pull request rule

    Open Pull requests, press Rules, then Add a rule. Choose When a pull request is opened or updated and write the target branch, main.

  3. Step 3: Choose the tests and the preview

    Pick the release suite, choose The pull request's Vercel preview as the address and press Save rule.

Good to know

Rehearsal's browsers cannot open a protected preview yet, so the previews you test must be public. If Vercel asks visitors to sign in to your previews, make them public first, as Protected previews explains.

On each pull request Link to On each pull request

  1. Step 1: The pull request opens or changes

    A check named Rehearsal appears on the pull request's newest commit straight away, reading "Waiting for Vercel to deploy this commit". On Pull requests in Rehearsal, the pull request's group shows Waiting for a deployment.

  2. Step 2: The preview is ready

    When Vercel reports the preview ready, the tests start against its address. The check reads "Queued. 3 tests will run." while they wait for a browser, then "Running 3 tests".

    The tests start this way only when Vercel reports the preview after Rehearsal has heard of the pull request. If Vercel deployed the commit first, as when you push a branch and open the pull request later, the check keeps waiting until Rehearsal looks for the preview 30 minutes after the pull request opened, as When no tests run explains, and the tests start then.

  3. Step 3: The run ends

    The check shows the result, a table of the tests and a link to the run, as What a check says describes.

Each new commit pushed to the pull request starts this again. The older commit's waiting check closes, and a run still testing the older commit stops, so only the newest commit is tested.

When no tests run Link to When no tests run

A waiting check always ends, so a required check never holds a pull request forever. If no deployment has arrived 30 minutes after the pull request opened or changed, Rehearsal asks GitHub once whether it missed one, and runs the tests if it did. Otherwise the check ends with one of these:

What happenedThe check readsConclusion
The deployment failedThe deployment failed, so there was nothing to testaction_required
No deployment arrived within 30 minutesRehearsal did not receive a deployment for this committimed_out
A newer commit arrivedA newer commit replaced this onecancelled
The pull request was closedThe pull request was closedcancelled

A failed or missing deployment leaves a required check blocking the merge, because nothing was tested. A newer commit or a closed pull request cancels the check instead, because its tests are no longer wanted.

A check that ended because the deployment failed or never arrived has no run behind it, so re-running it in GitHub does nothing. Fix the deployment and push a new commit to the pull request, which starts a new check.

Protected previews Link to Protected previews

The rule's Access to Vercel previews field takes the secret from Vercel's Protection Bypass for Automation, but runs do not send it yet, as the line under the field says. Until they do, test previews that anyone can open without signing in.

Pull requests from forks Link to Pull requests from forks

Rehearsal skips pull requests from forks, so they get no check. If GitHub requires the check, a pull request from a fork waits for one that never comes.

Branch deployments Link to Branch deployments

A branch or pattern rule can test Vercel's deployment of the branch instead, such as each deployment of main after a merge. There is nothing to wait for, so it opens no waiting check, and its check appears when the tests start, under a name such as Rehearsal · main. On Pull requests, those runs are grouped under the branch with the line Branch runs report here and block nothing.

Next steps Link to Next steps