Add choochoo validate to your CI pipeline to catch spec errors before they merge. Make sure you have installed the CLI and completed the Quickstart first.

GitHub Actions

Add this to .github/workflows/choochoo.yml:

name: ChooChoo Validate

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install ChooChoo CLI
        run: npm install -g @choochoo-works/cli

      - name: Validate
        run: choochoo validate ./choochoo/docs --quiet

The --quiet flag outputs JSON only, which is easier to parse in CI. The exit code tells you the result: 0 = all valid, 1 = validation errors, 10 = approval required (pipeline pauses until a human approves via The Station or CLI — treat as "pending", not "failed").

GitLab CI

Add this to .gitlab-ci.yml:

choochoo_validate:
  image: node:22
  script:
    - npm install -g @choochoo-works/cli
    - choochoo validate ./choochoo/docs --quiet
  only:
    - merge_requests
    - main

Pre-commit hook

You can also run validation as a Git pre-commit hook:

# Using husky
npm install husky --save-dev
npx husky install
npx husky add .husky/pre-commit "choochoo validate ./choochoo/docs --quiet"

Understanding CI results

Exit code	Meaning
0	All files valid
1	Validation errors found
10	APPROVAL_REQUIRED — a governance gate is blocking; treat as "pending", not "failed"

For detailed error information and exit codes, see Error Messages.

Next steps

• CLI Reference — Full reference for the validate command and all flags.
• Error Messages — Troubleshoot validation errors by error code.
• Agent Trace — Record agent traces alongside your CI checks.