At a glance
Reference for AI: CI/CD at a glance
Reference for AI: CI/CD at a glance
- Secret: store the project API key as a CI secret named
CHECKSUM_API_KEY. Checksum sets up the tests repository during onboarding, so there is nothing to initialize. - Cross-repo: if the tests live in a different repository than the pipeline, you also need a Personal Access Token with read access to the tests repo.
- Gate on
verdict: pass the build only whenverdictis"pass". Don’t gate on thepassed/failedcounts. - No cancel: cancelling a CI job only stops polling. An API-triggered Checksum run continues until it finishes.
- Sharding requires
checksumai4.4.0 or later on the tests branch.
Run Checksum with the GitHub Action
Thechecksum-ai/test-run-action action starts a Checksum run in a single step, with auto-heal on failure built in. The tests run in Checksum’s cloud, so your job doesn’t need Node, Playwright, or browsers. Add your API key as a repository secret named CHECKSUM_API_KEY (from Settings → Project Settings in the Checksum web app; in GitHub, go to Settings → Secrets and variables → Actions), then add this workflow:
pull_request, or via the GitHub API on push) and passes it to auto-heal, so healing progress shows up as a comment on the right PR. Checksum posts these PR comments itself through its GitHub App, so your workflow doesn’t need its own comment steps or pull-requests: write.
Choose which tests to run with exactly one of these inputs: grep (a name pattern), affected (only tests affected by the PR’s changes), suite-ids, test-ids, or collection-id. The endpoints behind them are described in Running Tests → Execution endpoints, and the complete inputs/outputs reference and changelog are in the action’s README.
Heal failures, with or without a PR
Withauto-heal: true, a failed run starts Auto-Healing automatically. By default the fixes arrive as a PR, and progress is reported as a comment on the originating PR, with no extra wiring on pull_request events. To start heal sessions without auto-creating a PR, add auto-create-pr: false:
Make the workflow wait and pass or fail
By default the action exits as soon as Checksum accepts the run (about 15 seconds), and you hear about results through the PR comment. Setwait: true if the workflow check itself should pass or fail on the outcome. The step succeeds only when the run’s verdict is pass. A failed run, an empty selection, a cancelled run, an infrastructure error, or a timeout all fail the step.
Split a large run across shards
Setshard-count (2–40, in grep and affected modes) to run the tests in parallel and merge the results into one verdict:
auto-heal from action v2.1.0 onward: once the shards merge, a merged run that ends failed is healed just like a non-sharded run. If the shards never merge, the heal is never evaluated. Older action versions reject the combination; @v2 already resolves to the latest 2.x. Check your suite against Sharding before using a large shard count.
Test each PR’s preview deployment
If every PR is deployed to its own preview URL, passenv-overrides (grep mode only) to point the run at it:
Choose the tests-repo branch
Ingrep mode, branch picks the branch of your tests repository that the run checks out. Leave it out to use the tests repo’s default branch. Set it explicitly when the workflow runs from your application repo, so the run (and any heal PR, which defaults to the run’s branch) uses your tests repo’s integration branch rather than the application PR’s branch:
Pin the action version
Use@v2 for compatible updates (recommended), @v2.0.0 for a release-specific tag, or a full commit SHA if you need a guarantee of immutability, since tags can technically be moved by the repo owner (see GitHub’s guidance on pinning third-party actions). @v1 still exists with the pre-sharding behavior but no longer gets updates.
Reference for AI: checksum-ai/test-run-action@v2
Reference for AI: checksum-ai/test-run-action@v2
pull_request, via the GitHub API on push.Required secrets
Action inputs
grep, affected, suite-ids, test-ids, or collection-id.Action outputs
Step exit with wait: true
Version pins
@v2 fails the step on an empty selection. Sharding requires checksumai ≥ 4.4.0 on the tests branch; older versions can fail to merge shard reports and delay the terminal verdict. Older action versions reject shard-count + auto-heal client-side. From application-code CI, set branch to the tests repo’s integration branch. PR comments come from Checksum’s GitHub App, so workflows need no comment steps and only pull-requests: read.Run the CLI in GitHub Actions
Use this when the tests should run on your own runner, for example to reach an app that’s only available on your network. Create.github/workflows/checksum-tests.yml in your tests repository:
CHECKSUM_API_KEY (required), plus the test user’s USERNAME and PASSWORD, your application’s BASE_URL, and its LOGIN_URL. Setting CI: true turns on report uploads and auto-heal PRs by default (see checksum.config.ts). Variables you set explicitly always override the downloaded .env (Environment variables). To run only the tests a PR affects, add --cksm-affected to the test command (Selecting tests).
If your tests live in another repository
When the workflow runs in your application repo but the tests live elsewhere, check out the tests repo with a Personal Access Token stored asTEST_REPO_PAT:
Try the workflow
- Commit the workflow file to your main branch.
- Go to Actions, select the workflow, and click Run workflow.
- Watch the run to confirm tests execute and the report appears in Test Results.
Reference for AI: CLI in GitHub Actions
Reference for AI: CLI in GitHub Actions
actions/checkout@v4 → npm install → npx playwright install --with-deps → npx checksumai dotenv --download --api-key="${{ secrets.CHECKSUM_API_KEY }}" → npx checksumai test with env vars below. Optional flags: --cksm-affected (PR-affected tests only), --cksm-auto-heal (heal failures).Secrets for the CLI workflow
CI: true sets defaults hostReports: true and autoHealPRs: true. Explicit env vars take precedence over the downloaded .env.Run the CLI in GitLab CI/CD
Add this job to your.gitlab-ci.yml:
--cksm-affected picks up the target branch from CI_MERGE_REQUEST_TARGET_BRANCH_NAME automatically.
If your tests live in another project
Clone the tests project with an access token stored asTEST_REPO_PAT:
Reference for AI: CLI in GitLab CI/CD
Reference for AI: CLI in GitLab CI/CD
node:20-bookworm. before_script: npm ci → npx playwright install --with-deps → npx checksumai dotenv --download --api-key="${CHECKSUM_API_KEY}". script: npx checksumai test. Set CI: "true". In merge-request pipelines, --cksm-affected reads CI_MERGE_REQUEST_TARGET_BRANCH_NAME.GitLab CI/CD variables
Trigger and gate a run from any CI system
Any CI system that can runcurl can use Checksum. Start a run, check its status until it finishes, and pass the build only when the verdict is "pass". On GitHub, the GitHub Action does exactly this for you and is usually simpler.
- Start the run. For PR checks, use
POST https://api.checksum.ai/public-api/v2/execution/grep, which accepts the PRbranch, a preview URL inenvOverrides, and ashardCountin one request. Save therunIdit returns. The other ways to start a run are in Execution endpoints. - Check the status with
GET https://api.checksum.ai/public-api/v1/execution/status/run/{runId}untilisTerminalistrue(Run status). - Gate on
verdict, not on the passed/failed counts. The verdict is only computed after sharded results merge, and it treats an empty selection as a failure. - Heal, if you like, by including an
autoHealblock when you start the run, or by callingPOST https://api.checksum.ai/public-api/v1/auto-healafterward (Auto-Healing).
${{ … }} expressions to your CI system’s variables. It needs a CHECKSUM_API_KEY secret, jq on the runner (preinstalled on ubuntu-latest), and a per-PR preview URL.
Example: a sharded PR check with curl
Example: full suite with auto-heal, gated on the verdict
Example: full suite with auto-heal, gated on the verdict
pass. When the run fails, Checksum starts healing automatically, so no separate heal call is needed. Needs curl, jq, and CHECKSUM_API_KEY.autoHeal, call POST /auto-heal with testRunId set to the run’s UUID (the runId above), not the dispatch name (see the next example).Example: other calls you can chain in a pipeline
Example: other calls you can chain in a pipeline
Reference for AI: REST API in any CI system
Reference for AI: REST API in any CI system
Authorization: Bearer $CHECKSUM_API_KEY and, with a body, Content-Type: application/json.envOverrides: application variables only.CIand keys starting withCHECKSUM_are rejected with400.- v1 execution endpoints can shard, but they run against the project’s configured branch and environment. For a PR branch with a preview URL, use v2 grep.
POST /v1/execution/suitewith{"shardCount": 4}returns{ "runId": "…", "name": null, "sharded": true }.POST /v1/auto-healreturns{ "batchId", "sessionIds", "failureCount", "testIds" }. PollGET /v1/auto-heal/batch/{batchId}.- API-triggered runs can’t be cancelled through the public API. Cancelling the CI job only stops polling.
Auto-heal tests that fail in CI
Checksum can fix the tests that failed in a CI run and open a PR with the fixes. You can opt in for a single run, or ask Checksum to turn it on for the whole project. For one run, addauto-heal: true to the GitHub Action, add --cksm-auto-heal to the CLI test command, or include an autoHeal block when you start a run through the API. With the CLI in GitHub Actions or GitLab, the repository, branch, and PR number are detected from the CI environment:
--cksm-auto-heal* flag set is in Running Tests → test flags.
Heal every failing CI run (project-wide)
autoHeal) takes priority over the project-wide setting for that run. See Auto-Healing for how healing works.
When to run your tests
Troubleshooting
The action step fails immediately with an empty selection
The action step fails immediately with an empty selection
@v2, a grep (or affected set) that matches no tests fails the step. Check your pattern with npx checksumai test --cksm-affected-dry-run or run the grep locally.A sharded run never reaches a verdict
A sharded run never reaches a verdict
checksumai version older than 4.4.0, so shard reports can’t merge. Upgrade, commit, and re-run. Always bound wait: true with wait-timeout-seconds.Heal PR opened against the wrong branch
Heal PR opened against the wrong branch
main). With the GitHub Action, set the branch input: healing defaults to the run’s branch. With the REST API, set autoHeal.branch; with the CLI, --cksm-auto-heal-branch. See Where healing runs.Cancelling the workflow didn't stop the run
Cancelling the workflow didn't stop the run
Reports don't show up in the dashboard
Reports don't show up in the dashboard
CI=true. Set CI: true in the job, or set options.hostReports: true in checksum.config.ts.Related
Running Tests
Sharding
Auto-Healing
The Checksum CLI
checksumai command and flag.