Preview deployments

Some checks need your app running, not just its code: performance, smoke tests, security scans and accessibility. Zof runs those against your pull request's preview deployment, a temporary copy of your app built from the pull request's exact commit.

How Zof finds your preview

When your host finishes a preview, it tells GitHub that the commit is deployed and at which address. Zof listens for that, and checks three things before testing:

• the deployment is for the pull request's latest commit;
• the pull request is still open;
• the deployment isn't production. Zof never tests a pull request against production.

Public previews

Zof identifies public previews through GitHub's standard deployment reports. You can use a hosting provider or deploy from your own CI. Report the deployed commit, a public HTTPS address and a successful non-production deployment to GitHub.

A public preview needs no bypass secret. The same commit and non-production checks apply to every hosting setup.

Report deployments from your own CI

If you deploy with your own workflow, add two steps around your deploy so GitHub knows which commit runs where. Give the job deployments: write permission, and keep the address public over HTTPS.

The example uses context.sha and assumes that is the exact commit your workflow builds and deploys. If your deploy uses a different checkout or an existing build artifact, report that artifact's actual source commit instead. In a pull_request workflow, context.sha is usually GitHub's temporary merge commit. For a preview of the PR's latest commit, explicitly build and deploy the PR head; never report the PR head for an artifact built from a different commit.

      - name: Report deployment start to GitHub
        id: gh_deploy
        uses: actions/github-script@v7
        with:
          script: |
            const d = await github.rest.repos.createDeployment({
              owner: context.repo.owner, repo: context.repo.repo,
              ref: context.sha, environment: 'dev',
              production_environment: false, auto_merge: false, required_contexts: [],
            });
            core.setOutput('id', String(d.data.id));

      # ... your existing deploy steps ...

      - name: Report deployment result to GitHub
        if: always() && steps.gh_deploy.outputs.id != ''
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.repos.createDeploymentStatus({
              owner: context.repo.owner, repo: context.repo.repo,
              deployment_id: Number('${{ steps.gh_deploy.outputs.id }}'),
              state: '${{ job.status }}' === 'success' ? 'success' : 'failure',
              environment_url: 'https://your-preview.example.com/',
            });

Report success only once the new version answers, for example after a health check. Never mark a production deployment as production_environment: false, because Zof relies on it to keep pull requests away from production.

Protected previews

A preview that requires authentication needs an access method Zof supports. Vercel's Protection Bypass for Automation is currently the supported method. Other login, VPN and custom authentication methods are not supported yet.

Protected Vercel previews

If your Vercel previews ask for a login, Zof's checks would stop at it. Vercel offers a Protection Bypass for Automation secret for this. Copy it from your Vercel project settings, then paste it into Preview access on the repository in Zof.

An admin sets it once per repository. Zof stores it encrypted and never shows it again. Zof sends it only to your own Vercel previews, made by the Vercel app, at the addresses you allow. To stop Zof using it, remove it in Zof and rotate it in Vercel.

Not supported yet

Protected previews on hosts other than Vercel aren't supported yet. A shared staging server cannot verify a feature PR whose latest commit differs from the deployed commit; an exact-commit promotion PR can qualify as described above. See What's built.