Skip to content
Documentation menu

CI

Deterministic, non-interactive, exit-code driven. By default only findings that are new relative to your baseline can fail a build.

Why only new findings

A project with existing debt should be able to adopt Little Owl without fixing everything first. The gate asks a narrower question than a linter does: did this change make the codebase worse? Existing problems stay visible in check, but they do not block anyone.

Pass --all when you want the stricter reading, once you have paid the debt down.

little-owl ci --base origin/main

$ little-owl ci --base origin/main
little-owl: DEGRADED
findings: 1 error, 3 warning, 0 info
overall: 89 -> 83
  error: services/orders.ts:12 Circular dependency
  warning: app/checkout/page.tsx:1 <CheckoutPage> 486 lines

result: fail (1 error-level finding;
              overall score dropped 6 points)

$ echo $?
1

Exit codes

  • 0 — nothing crossed the gate you configured.
  • 1 — a finding at or above failOn, or the overall score fell further than maxOverallDrop.

Gates

little-owl ci                        # fail on new errors (default)
little-owl ci --fail-on warning      # stricter
little-owl ci --fail-on never        # report only, never fail
little-owl ci --max-drop 3           # fail if overall falls more than 3 points
little-owl ci --all                  # count pre-existing findings too
little-owl ci --json                 # machine-readable

Command-line flags win over the ci block in your config file, so a workflow can be stricter than local runs without editing the config.

Commit your baseline

.little-owl/baseline.json belongs in version control. It is what CI compares against, and committing it means the whole team is measured against the same agreed state rather than against whatever their machine computed.

GitHub Actions

.github/workflows/little-owl.yml

name: Little Owl Code

on:
  pull_request:

jobs:
  little-owl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # so the base branch is available to compare against

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npx little-owl-code ci --base origin/${{ github.base_ref }}

Machine-readable output

Every reporting command accepts --json on a versioned schema: schemaVersion only changes when a field is removed or its meaning changes, so new optional fields will not break your tooling.

Fields worth knowing

  • status — healthy, needs-review or degraded.
  • newFindings and resolvedFindings — what this change added and what it fixed.
  • drift — the per-score movement against the baseline.
  • truncated — true when the scan hit its file limit, so a partial analysis can never be read as a clean one.
  • ci.passed and ci.reasons — the verdict and why.

Other CI systems

There is nothing GitHub-specific about it. Any runner that can install a package and read an exit code will do — install little-owl-code, make sure the base branch is fetched, and run little-owl ci --base <ref>.