Skip to content
Chisel

Run chisel in GitHub Actions

You want pull requests to fail when chisel finds violations: the same contract as the local pre-commit hook, applied remotely. This guide adds a CI job that runs the check on every PR.

Minimal job

Section titled “Minimal job”

Here’s a job that runs chisel check on a FastAPI backend. Adjust the path and --strict to match your project.

.github/workflows/ci.yml
jobs:
  python:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install chisel
      - run: chisel check ./your-backend --strict

For a SvelteKit frontend:

  typescript:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g chisel-js
      - run: chisel-js check ./your-frontend

This assumes chisel.config.json is committed — run chisel-js init once locally and commit it. CI should never be the place the topology gets detected: a build that decides its own rule set is a build whose results you cannot compare across commits. If the file is missing, chisel-js falls back to detection and warns on stderr rather than failing.

CI runs the checker the same way a human does, no special mode, so the behaviour you see locally is exactly what blocks a pull request.

Capture the JSON report for agents

Section titled “Capture the JSON report for agents”

If a bot or an agent consumes CI output, pipe the JSON to a file and upload it as an artifact. Use || true so a non-zero exit doesn’t stop the step before the artifact is uploaded.

- run: chisel check . --json > chisel-report.json || true
- uses: actions/upload-artifact@v4
  with: { name: chisel-report, path: chisel-report.json }

The JSON shape is documented in Understand a violation.

What’s next

Section titled “What’s next”