GitHub Action

The Action installs @izri/cli, runs the scope check, optionally triggers a test run, and reports the result. It is a composite action — no JavaScript bundle, just bash — so it adds a few seconds to a workflow, not a build step.

name: izri
on:
  pull_request:
    branches: [main]

jobs:
  izri:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: legendify-dev/izri/apps/github-action@v1
        with:
          api-token: ${{ secrets.IZRI_API_TOKEN }}

fetch-depth: 0 is required

The scope check diffs your head against origin/<base>. A shallow clone — the actions/checkout default — has no base ref to resolve, so the check fails before it starts. Either set fetch-depth: 0 or fetch the base ref explicitly.

Inputs

Input	Required	Default	What it does
api-token	yes	—	Your Izri API token. Starts with izri_. Store it as a repository secret, never inline.
api-url	no	https://api.izri.ai	Override for self-hosted installs.
project-id	no	(auto)	Project ULID. When omitted the CLI resolves it from your git origin remote.
mode	no	both	scope, tests, or both.
base-ref	no	(auto)	Git base to diff against. Resolves to origin/${{ github.base_ref }} on pull requests and origin/<default-branch> on pushes.
wait-for-results	no	true	When mode includes tests, block until the run reaches a terminal status.
fail-on-finding	no	true	Exit non-zero on hard scope findings or a non-passing test run.
cli-version	no	latest	Version range for @izri/cli. Pin to a tag for reproducible CI.

Choosing a mode

• scope is deterministic and fast. No test run, no waiting. Good as a required check on every PR.
• tests triggers a run and (by default) waits for it.
• both is the default and what you want unless you have a reason otherwise.

Pin cli-version for reproducibility

latest means a CLI release can change your CI behavior without a commit in your repository. Pin it once you're past evaluation:

with:
  api-token: ${{ secrets.IZRI_API_TOKEN }}
  cli-version: '0.1.0'

Outputs

Output	Value
scope-alignment-score	Alignment score 0–100. Empty string when mode=tests.
scope-findings-count	Total scope findings, all severities. Empty string when mode=tests.
scope-hard-findings-count	Findings at severity: error — the only category that blocks by default.
test-run-id	The Izri test-run identifier. Empty string when mode=scope.

Outputs are empty strings, not zeros, when their mode didn't run. Test for emptiness before doing arithmetic:

      - uses: legendify-dev/izri/apps/github-action@v1
        id: izri
        with:
          api-token: ${{ secrets.IZRI_API_TOKEN }}

      - name: Comment when alignment is low
        if: steps.izri.outputs.scope-alignment-score != '' &&
            fromJSON(steps.izri.outputs.scope-alignment-score) < 60
        run: echo "Scope alignment is ${{ steps.izri.outputs.scope-alignment-score }}"

Making the verdict binding

Until you require it, the check reports but enforces nothing.

Settings → Branches → Branch protection rules → Require status checks to pass, then add izri/quality.

Require the umbrella, not the individual signals. The umbrella already aggregates them and handles skipped signals correctly; requiring izri/visual directly would block every backend-only PR, because that signal legitimately skips when no UI route changed.

Non-blocking evaluation mode

To surface findings without failing anyone's build while you evaluate:

with:
  api-token: ${{ secrets.IZRI_API_TOKEN }}
  fail-on-finding: false

The check still publishes and the sticky comment still appears — the workflow just won't go red.

Related

• CLI — the same checks from your terminal.
• Verdicts and exit codes — what the Action's exit status means.
• .izri/scope.yml — tune what the scope signal considers sensitive.