Stepshots logoStepshots

CI & Automation

Run the Stepshots CLI in CI — machine-readable --json output, exit codes, verify drift checks, dry-run validation, and the hauju/stepshots GitHub Action for recording and publishing demos in pipelines.

Overview

Every Stepshots command runs headless and non-interactive, so the CLI fits cleanly into CI pipelines and agent workflows. This guide covers the pieces that matter for automation: machine-readable output, exit codes, drift checks, and the ready-made GitHub Action.

Machine-readable output

Pass --json to any command to get structured output on stdout instead of human-formatted text. It's the same flag everywhere — for AI agents and automation:

bash
stepshots verify --json > report.json
stepshots list --json
stepshots doctor --json

Errors are emitted as JSON too, with an error category, so a pipeline can branch on what went wrong.

Exit codes

The CLI exits 0 on success and maps each failure category to a stable code, so a pipeline can react without parsing text:

Code Category Meaning
0 — Success.
1 config Config, I/O, upgrade, or other general error.
2 browser Chrome failed to launch or a CDP call failed.
3 action A step couldn't execute (e.g. a selector no longer matches).
4 bundle Failed to build or read the .stepshot bundle.
5 upload / auth Upload failed or authentication was rejected.

Validate before recording

record --dry-run parses and validates the config and reports what would be recorded without launching a browser — a fast config check for pull requests:

bash
stepshots record --dry-run

Detect drift with verify

stepshots verify replays your tutorials against the live app and reports which steps or annotations no longer match, without writing a bundle. It's the check to run on a schedule so a redesign never silently breaks your demos:

bash
stepshots verify --fail-on warn --save-failures ./drift
  • --fail-on fail (default) exits non-zero only when a step can no longer execute.
  • --fail-on warn also fails on annotation drift (an annotation that lost its anchor).
  • --save-failures <dir> writes a screenshot of the page at each failure (defaults to output/).

Combine it with --json for a report carrying a repair hint per failure.

Check the environment

stepshots doctor verifies the browser, config, server reachability, and login in one pass. Run it early in a job to fail fast with a clear message when something is misconfigured:

bash
stepshots doctor --json

Authenticate and publish

In CI you can't complete a browser login, so authenticate with an API key via STEPSHOTS_TOKEN (generate one from API Keys):

bash
export STEPSHOTS_TOKEN=****
stepshots upload output/onboarding.stepshot --public

Add --public to publish uploaded demos immediately, or --demo-id <id> to replace an existing demo in place.

Chrome sandbox in CI

When the CI environment variable is set, the CLI launches Chrome with --no-sandbox, --disable-gpu, and --disable-dev-shm-usage, which is required in most containerized runners. GitHub Actions sets CI=true automatically. If you run stepshots in another CI system or a container that doesn't set it, export it yourself:

bash
export CI=true

GitHub Action

The repo ships a composite GitHub Action, hauju/stepshots, that installs the CLI, sets up Chrome, and runs record or verify for you.

Record and publish on every push to main:

yaml
- uses: hauju/stepshots@main
  with:
    command: record
    config: demo/stepshots.config.json
    upload: "true"
    token: ${{ secrets.STEPSHOTS_TOKEN }}

Check demo freshness on a schedule:

yaml
- uses: hauju/stepshots@main
  with:
    command: verify
    config: demo/stepshots.config.json
    fail-on: warn

The verify run fails the job when drift is found, writes a freshness summary to the job summary, and leaves output/verify-report.json for tooling.

Inputs

Input Default Description
command record record (capture bundles) or verify (drift check, writes no bundles).
config stepshots.config.json Path to the config file.
tutorials all Comma-separated tutorial keys to record or verify.
output output Output directory for bundles (record) or failure screenshots and the report (verify).
fail-on fail Verify only: fail on fail (broken steps) or warn (also annotation drift).
upload false Upload bundles after recording.
token — Stepshots API token (required when upload is true).
server https://stepshots.com Server URL.
demo-id — Replace an existing demo instead of creating a new one.
title — Override the demo title on upload.
version main Stepshots CLI version (git ref) to install.

Outputs

Output Description
bundles Newline-separated list of recorded .stepshot files (record command only).
report Path to the verify JSON report (verify command only).
Navigation