The CARL CLI is designed to be CI-native. Its exit codes are stable, its JSON output is a stable contract, and it runs in under a minute on most repositories. This guide walks through three common CI integrations:

1. Running CARL on every PR and failing the build if the level drops.
2. Posting the report as a PR comment.
3. Publishing the JSON report as a workflow artifact for downstream tools.

The examples use GitHub Actions; the same approach applies to GitLab CI, CircleCI, Buildkite, and every other modern CI.

Prerequisites

• A repository that already runs CI on every PR.
• Node 22+ available on CI runners (GitHub Actions ubuntu-latest has this by default once you set actions/setup-node@v4).
• pnpm or npm (both work).

Step 1 — Add a CARL step to the workflow

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  carl:
    name: CARL assessment
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write # for the comment step below; safe to omit if unused
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - uses: pnpm/action-setup@v4
        with:
          version: 9
          run_install: false

      - uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: Run CARL
        run:
          pnpm dlx @wentzel/carl assess --min-level 3 --json > carl-report.json

JSON output goes to stdout; the CLI's progress line only appears for the pretty format, so no extra flag is needed in CI. The --min-level 3 flag makes the CLI exit non-zero if the assessed level drops below L3 (Reviewed). --min-level accepts any rung on the 0–6 ladder (0 Manual, 1 Scripted, 2 Tested, 3 Reviewed, 4 Agent-driven, 5 Creates a business, 6 Runs a business). Tune the threshold to your team's current level — raising it later is straightforward.

Step 2 — Upload the report as an artifact

- name: Upload CARL report
  if: always() # upload even if the min-level gate failed
  uses: actions/upload-artifact@v4
  with:
    name: carl-report
    path: carl-report.json
    retention-days: 30

The if: always() is important — when the level gate fails, you still want the artifact to debug why.

Step 3 — Comment the summary on the PR

Step 4 — Require the check in branch protection

In GitHub → Settings → Branches → default-branch rule, add CARL assessment to the list of required status checks. With the rule in place, a PR that drops the level below --min-level cannot be merged without an admin override.

Strategies for introducing CARL to an existing repository

Monorepos

For monorepos, use the same workflow but point at application directories:

- name: CARL — web app
  run:
    pnpm dlx @wentzel/carl assess ./apps/web --min-level 3 --json >
    web-report.json

- name: CARL — engine
  run:
    pnpm dlx @wentzel/carl assess ./packages/engine --min-level 3 --json >
    engine-report.json

Or run once at the repo root and let the CLI enumerate applications — see Monorepo setup for details.

Caching

The CARL CLI is fast enough that caching its output usually doesn't pay. If your repository is genuinely large (tens of thousands of files) and your CI feedback time matters, consider:

• Caching the CARL install by using pnpm install instead of pnpm dlx.
• Running CARL only on PRs that touch source files (use paths-ignore to exclude docs-only PRs).

Related

• CLI — the command surface CARL exposes.
• Reading your report — interpreting what CI surfaces on the PR.
• Monorepo setup — how CARL handles per-application assessment in monorepos.