CI/CD Integration
Use Supercheck CLI in GitHub Actions, GitLab CI, and Docker pipelinesEdit
Trigger jobs, wait for results, and gate deployments on test outcomes from any CI/CD platform.
Secrets
Set these in your CI/CD platform's secret store:
| Secret | Description |
|---|---|
SUPERCHECK_TRIGGER_KEY | Job-specific trigger key (sck_trigger_*) for supercheck job trigger |
SUPERCHECK_TOKEN | CLI token (sck_live_*) for general API commands and job trigger --wait |
Pass the job ID as the argument to supercheck job trigger; the CLI does not read a default job ID from an environment variable. Cloud users need no URL setting.
Pipelines
Reusable workflow
name: Supercheck Tests
on:
push:
branches: [main]
pull_request:
jobs:
test:
uses: supercheck-io/supercheck/.github/workflows/supercheck-cli.yml@main
secrets:
SUPERCHECK_TRIGGER_KEY: ${{ secrets.SUPERCHECK_TRIGGER_KEY }}
SUPERCHECK_TOKEN: ${{ secrets.SUPERCHECK_TOKEN }}
with:
job-id: ${{ vars.SUPERCHECK_JOB_ID }}
wait: true
timeout: 300SUPERCHECK_TRIGGER_KEY starts the run. SUPERCHECK_TOKEN is only needed here because the example uses wait: true.
Manual setup
name: E2E Tests
on:
push:
branches: [main]
pull_request:
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
- name: Install Supercheck CLI
run: npm install -g @supercheck/cli
- name: Run E2E Tests
run: supercheck --json job trigger ${{ vars.JOB_ID }} --wait
env:
SUPERCHECK_TRIGGER_KEY: ${{ secrets.SUPERCHECK_TRIGGER_KEY }}
SUPERCHECK_TOKEN: ${{ secrets.SUPERCHECK_TOKEN }}
- name: Deploy Config
if: github.ref == 'refs/heads/main'
run: supercheck deploy --force
env:
SUPERCHECK_TOKEN: ${{ secrets.SUPERCHECK_TOKEN }}Deployment gating
Use the CLI exit code to stop the workflow when the run fails, is blocked, or times out:
- name: Gate Deployment
run: |
supercheck job trigger "${{ vars.JOB_ID }}" --wait
env:
SUPERCHECK_TRIGGER_KEY: ${{ secrets.SUPERCHECK_TRIGGER_KEY }}
SUPERCHECK_TOKEN: ${{ secrets.SUPERCHECK_TOKEN }}Exit Codes
| Code | Meaning | CI/CD action |
|---|---|---|
0 | Success | Continue pipeline |
1 | General error (test failure, validation) | Block deployment |
2 | Auth error | Check token configuration |
3 | Config error | Fix supercheck.config.ts |
4 | API error | Check connectivity |
5 | Timeout | Increase --timeout value |
130 | Interrupted | Stream cancelled with Ctrl+C |
In a non-interactive environment, an operation that requires confirmation refuses with exit code 3 and a CONFIRMATION_REQUIRED error. Review the JSON plan, then explicitly pass --force for an authorized write. Authentication failures remain exit code 2.
Best Practices
| Practice | How |
|---|---|
| Machine-readable results | Use --json; add --envelope with --json for pagination metadata (default list arrays remain compatible) |
| Inspect before writing | supercheck diff --json or supercheck deploy --dry-run --json |
| Block until tests finish | Use --wait, and set --timeout to suit your suite |
| Resume a wait | supercheck run wait <run-id> never triggers a new run |
| Least privilege | Use trigger keys (sck_trigger_*) for single-job triggers |
| Preview config changes | Run supercheck diff in PRs |
| Faster builds | Cache the CLI in your CI/CD environment |