Run browser tests in an existing CI job

zerocheck run works in any CI job that can run Node.js 20.19 or newer. You write the job: the CLI has no workflow generator, pull request comment, job summary or JUnit report, and there is no GitHub App to install. The CLI's exit code is what your pipeline reads.

CI is optional, and it is not part of standard onboarding. We start with the web app and the CLI on your machine, then you can add a CI job when your repository tests are useful.

What the job needs

• Your repository, with zerocheck.yaml, its YAML tests and zerocheck in its devDependencies.
• ZEROCHECK_API set to your instance URL. It has no default.
• ZEROCHECK_TOKEN set to a project token, created in Settings in the web app. Device login is for people, not CI.
• Chromium, installed on the runner.
• An environment in zerocheck.yaml whose URL the runner can reach.
• A CI secret for every variable your test credentials reference. A missing variable stops the run before it starts.

An example GitHub Actions workflow

This is an example to adapt, not a generated file. Add your own application startup or deployment wait where you need it:

name: Zerocheck
on:
  workflow_dispatch:
  pull_request:

permissions:
  contents: read

jobs:
  browser-tests:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      ZEROCHECK_API: ${{ vars.ZEROCHECK_API }}
      ZEROCHECK_TOKEN: ${{ secrets.ZEROCHECK_TOKEN }}
      # Add only the secret variables zerocheck.yaml references.
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx zerocheck run --env staging --json zerocheck-run.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: zerocheck-run
          path: zerocheck-run.json
          if-no-files-found: ignore

Pull requests from forks do not receive your repository's secrets, so this job cannot run for them. Read the run record with --json, and open the Results: link it prints to see the evidence behind your instance's sign-in.

Choose your merge policy

A failed blocking test exits 1, and anything without a verdict exits 2, so either one fails the job. To stop a merge on that failure, configure the job as a required check in your repository's branch protection or ruleset. Zerocheck does not do that for you.

Tests default to blocks_merge: true. A failed expected outcome in a test with blocks_merge: false stays visible without changing the exit code, though a test that could not complete still exits 2. Add --fail-on-flaky if a blocking test that passed only after a transient retry should also fail the job.

What a CI result does and does not prove

A CLI run tests the URL configured for that environment. It does not know which commit that URL is serving, and a CLI run record does not carry the repository, branch, commit or pull request. Confirm that the environment serves the change you mean to test, for example by waiting for your preview deployment or by starting the app on the runner.

Test selection is explicit by file path; it is not inferred from a code diff. A CI runner counts as a local browser, so it can reach what that runner can reach. Your instance makes every decision and keeps the results.

Schedules

Zerocheck has no built-in scheduler. If you need tests on a schedule, add a schedule to your own CI job and choose the environment. Zerocheck is not an incident-monitoring or alerting service.

Result interpretation · Credentials and data · CLI