CI Integration

Clarx is designed to run in CI. Add it to any pipeline to enforce a minimum score on every pull request.

Two shortcuts before writing YAML by hand: if you use the Clarx MCP server, ask your agent — "Add a Clarx PR gate at min score 70" — and it generates this workflow for you. Or use the composite action below.

GitHub Actions

Basic score gate

# .github/workflows/clarx.yml
name: Clarx AI-Readiness

on:
  pull_request:
    branches: [main]

jobs:
  score:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @clarxai/cli score --min-score 70

SARIF for GitHub Code Scanning

name: Clarx SARIF

on:
  pull_request:
    branches: [main]

jobs:
  score:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @clarxai/cli score --format sarif > clarx.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: clarx.sarif

PR comment with markdown report

name: Clarx Score

on:
  pull_request:

jobs:
  score:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Score and post as PR comment
        uses: actions/github-script@v7
        with:
          script: |
            const { execSync } = require('child_process');
            const report = execSync('npx @clarxai/cli score --format markdown').toString();
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            });

      - name: Enforce minimum score
        run: npx @clarxai/cli score --min-score 65

Composite action

One step instead of hand-rolled YAML — score gate, SARIF, and report artifact behind inputs:

name: Clarx

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  security-events: write # only if upload-sarif: true

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

      - uses: Gernika-Labs/clarx-action@v1
        with:
          min-score: '70'
          upload-sarif: 'true'

Input	Default	Description
`path`	`.`	Directory to scan
`min-score`	—	Fail if overall score is lower
`min-pillar-score`	—	Fail if any pillar is lower
`cli-version`	`0.1.11`	npm version of `@clarxai/cli`
`ignore`	—	Comma-separated globs (`--ignore`)
`upload-sarif`	`false`	Upload findings to Code Scanning
`upload-artifact`	`false`	Upload markdown report artifact

Branch protection

To block merges when the gate fails: GitHub → Settings → Branches → your protection rule → enable Require status checks to pass before merging → add the job name (e.g. clarx). The check becomes selectable after its first run on a PR.

Fork PRs are safe with the plain pull_request trigger — Clarx needs no secrets to score. Do not use pull_request_target.

GitLab CI

clarx:
  image: node:20
  script:
    - npx @clarxai/cli score --min-score 70 --format json | tee clarx-report.json
  artifacts:
    paths:
      - clarx-report.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Recommended thresholds

Start conservative. A low threshold that passes lets teams adopt Clarx without blocking work. Raise it incrementally.

Phase	Recommended threshold
Initial adoption	`--min-score 50` (tolerates one hard failure under the graduated floor)
Stabilized baseline	`--min-score 65`
Target state	`--min-score 80`

Use --ui text or --format json in CI — the interactive TUI is skipped automatically in non-TTY environments.

Do not set a threshold higher than the current score on main. The first run should always pass on the existing codebase.

Ignoring paths

Use --ignore to exclude generated directories that are not in .gitignore:

npx @clarxai/cli score --ignore "**/.next,**/dist,**/coverage"

Or declare them in clarx-manifest.json under generated — the engine always excludes declared generated paths automatically.

CI Integration

On this page