Severity Configuration¶

abicheck classifies every detected change into one of four issue categories, each with a configurable severity level that controls exit codes and report presentation. Severity is layered on top of the overall verdict — it doesn't replace it.

Severity is the last step of the CI gating pipeline (classify → suppress → severity → exit code), and any active severity setting — a --severity-* flag or a severity value in .abicheck.yml — switches compare to the severity-based exit-code scheme. See CI Gating for how it combines with policies, suppressions, and baselines.

Issue categories¶

Every ChangeKind is assigned to exactly one of these categories:

Category	What it covers	Default severity
abi_breaking	Clear ABI/API incompatibilities (e.g. `func_removed`, `type_size_changed`)	`error`
potential_breaking	Source-level breaks and deployment risk (e.g. `enum_member_renamed`, `symbol_version_required_added`)	`warning`
quality_issues	Problematic behaviors that don't break compatibility (e.g. `visibility_leak`, `soname_missing`, `func_noexcept_added`)	`warning`
addition	New public API surface (e.g. `func_added`, `type_added`, `enum_member_added`)	`info`

The category assignment is based on canonical kind sets defined in checker_policy.py and respects the active --policy (e.g. sdk_vendor downgrades enum_member_renamed from potential_breaking to quality_issues).

Severity levels¶

Each category can be set to one of three levels:

Level	Report presentation	Exit code impact
`error`	Flagged prominently with badge	Contributes to non-zero exit code
`warning`	Shown as a warning with badge	Does not affect exit code
`info`	Informational, neutral	Does not affect exit code

CLI options¶

Presets¶

# Use the default preset (explicit)
abicheck compare old.json new.json --severity-preset default

# Strict: everything is an error (exits non-zero on any finding)
abicheck compare old.json new.json --severity-preset strict

# Info-only: purely informational (always exits 0)
abicheck compare old.json new.json --severity-preset info-only

Per-category overrides¶

Override individual categories on top of a preset:

# Default preset but fail on API additions too
abicheck compare old.json new.json --severity-addition error

# Strict preset but ignore quality issues
abicheck compare old.json new.json --severity-preset strict --severity-quality-issues info

# Only fail on binary ABI breaks, everything else informational
abicheck compare old.json new.json --severity-preset info-only --severity-abi-breaking error

Available flags: - --severity-abi-breaking {error,warning,info} - --severity-potential-breaking {error,warning,info} - --severity-quality-issues {error,warning,info} - --severity-addition {error,warning,info}

Presets reference¶

See Severity presets for the exact abi_breaking/potential_breaking/quality_issues/addition level each preset assigns — that table is the authority compare's exit-code computation follows; this page only documents how to select and override it.

Exit codes¶

When any severity setting is active — a --severity-* flag or a severity value in .abicheck.yml — the exit code is computed from the severity configuration instead of the legacy verdict system. See Severity-aware exit codes for the exact code-to-condition table; the highest applicable code wins. Without any active severity setting (no --severity-* flag and no config severity value), the legacy verdict-based exit codes apply (see exit codes reference).

Report output¶

Markdown¶

When severity is configured, the markdown report includes:

Severity Configuration table — shows the configured level, finding count, and exit impact for each category.
Section badges — each change section header includes the severity level badge (e.g. ## ❌ Breaking Changes ❌ \ERROR``).

JSON¶

The JSON output includes a severity object when severity is configured:

{
  "severity": {
    "config": {
      "abi_breaking": "error",
      "potential_breaking": "warning",
      "quality_issues": "warning",
      "addition": "info"
    },
    "categories": {
      "abi_breaking": {"severity": "error", "count": 2},
      "potential_breaking": {"severity": "warning", "count": 1},
      "quality_issues": {"severity": "warning", "count": 0},
      "addition": {"severity": "info", "count": 3}
    },
    "exit_code": 4
  }
}

Policy interaction¶

The severity system respects the active policy (--policy). For example, under sdk_vendor, kinds that are downgraded from API_BREAK to COMPATIBLE are reclassified from potential_breaking to quality_issues or addition accordingly.

This means --policy sdk_vendor --severity-preset default will not exit non-zero for changes that the sdk_vendor policy downgrades — for example, kinds moved from potential_breaking to quality_issues or addition are demoted to warning or info under the default preset. However, the strict preset maps all categories (including quality_issues and addition) to error, so --policy sdk_vendor --severity-preset strict will still exit non-zero for any detected changes, even those the policy downgrades.

GitHub Action¶

The GitHub Action supports severity configuration via inputs:

- uses: abicheck/abicheck@v0.5.0
  with:
    old-library: libfoo-v1.json
    new-library: libfoo-v2.json
    severity-addition: error        # fail on new API additions
    # severity-preset: strict       # or use a preset

For arbitrary --severity-* overrides not exposed as inputs, use extra-args:

- uses: abicheck/abicheck@v0.5.0
  with:
    old-library: libfoo-v1.json
    new-library: libfoo-v2.json
    extra-args: '--severity-quality-issues error --severity-potential-breaking info'