mode |
no |
compare |
Operation mode. The Action exposes five analysis modes, mirroring abicheck's five core per-library CLI commands (compare/dump/scan/ deps tree/deps compare — ADR-043; the CLI additionally has project-orchestration commands like aggregate and project plan (ADR-054) that this Action does not expose as separate modes): "compare" (default) compares two ABI surfaces — old-library/new-library may be single binaries/snapshots OR directories/packages, in which case abicheck fans out to a per-library comparison automatically (no separate mode); "dump" generates a JSON baseline snapshot from a single library (now also embeds optional L3/L4/L5 build-source evidence via source/build inputs); "scan" runs the deterministic source-intelligence orchestrator (classify → always-on pattern/cross-source tier → pinned evidence level, optionally compared against a baseline) — the entry point for source scans; "deps-tree" resolves transitive dependencies and symbol bindings for one binary (Linux ELF); "deps-compare" compares a binary's full dependency stack across two sysroots (Linux ELF). |
old-library |
no |
— |
Path to the old library, JSON snapshot, or ABICC Perl dump. Required when mode=compare. May also be a directory or package (RPM, Deb, tar, conda, wheel) — abicheck then fans out to a per-library comparison automatically. |
new-library |
no |
— |
Path to the new (current) library, binary, or JSON snapshot. Required for compare, dump (unless a source-only sources/build-info/compile-db input is given), scan, and deps-tree/deps-compare modes. May be a directory or package (RPM, Deb, tar, conda, wheel) ONLY in compare mode, matching old-library — compare then fans out to a per-library comparison automatically. dump and scan each analyse exactly one artifact and reject a directory/package with an error (they have no per-library fan-out); for a multi-library release, dump/scan each library individually or use compare instead. |
new-library-set |
no |
— |
scan mode only (ADR-056). Audit a set of libraries with no old side, as one operation: a directory (every discoverable shared library in it) or an explicit comma-separated path list. Maps to scan --artifact-set. Mutually exclusive with new-library and with against/abi-baseline (audit-only — no old-side comparison for a set). For a multi-library release comparison against an old side, use mode: compare with a directory/package operand instead. |
debug-info1 |
no |
— |
Debug info package for old side (RPM/Deb/tar). compare mode, directory/package operands only. |
debug-info2 |
no |
— |
Debug info package for new side (RPM/Deb/tar). compare mode, directory/package operands only. |
devel-pkg1 |
no |
— |
Development package with headers for old side. compare mode, directory/package operands only. |
devel-pkg2 |
no |
— |
Development package with headers for new side. compare mode, directory/package operands only. |
dso-only |
no |
false |
Only compare shared objects, skip executables. compare mode, directory/package operands only. |
include-private-dso |
no |
false |
Include private (non-public) shared objects from non-standard paths. compare mode, directory/package operands only. |
keep-extracted |
no |
false |
Keep extracted temporary files for debugging. compare mode, directory/package operands only. |
fail-on-removed-library |
no |
false |
Exit 8 when a library present in old is absent in new. compare mode, directory/package operands only. |
header |
no |
— |
Public header file(s) applied to both sides (space-separated). Required when input is an ELF binary; ignored for JSON snapshots. If old and new actually declare different header sets (e.g. a new release added a header), set old-header/new-header instead -- a bare header parses BOTH snapshots against the same files, which silently hides the removed/added declarations you're trying to check. |
old-header |
no |
— |
Public header(s) for the old side only (overrides header for old). Space-separated. |
new-header |
no |
— |
Public header(s) for the new side only (overrides header for new). Space-separated. |
include |
no |
— |
Extra include directories for castxml, applied to both sides. Space-separated. |
old-include |
no |
— |
Include directories for old side only. Space-separated. |
new-include |
no |
— |
Include directories for new side only. Space-separated. |
old-version |
no |
old |
Version label for the old library (embedded in reports). |
new-version |
no |
new |
Version label for the new library (embedded in reports). |
lang |
no |
c++ |
Language mode for header AST parsing: "c++" or "c". |
ast-frontend |
no |
— |
L2 header-AST frontend for native-binary inputs: "auto" (resolves to castxml and never changes producer unless the CLI's --allow-ast-frontend-fallback flag is also passed via extra-args (or ABICHECK_ALLOW_AST_FALLBACK=1 is set) — with that opt-in, a recognized castxml toolchain-version mismatch or direct-include-guard failure falls back to clang, G16; without it, and on any host with no castxml at all, auto does not silently switch to clang — the command fails asking you to install castxml or pass ast-frontend: clang explicitly), "castxml" (default), "clang" (clang -ast-dump=json; explicit opt-in for clang-only hosts), or "hybrid" (runs both and merges them; needs both tools installed on the runner, never auto-selected). Applies to dump, scan, and compare mode with a single-pair (non-directory, non-package) operand — the per-library fan-out a directory/package compare uses never threads this L2 context to each pair's header dump, so a value other than "auto" (the no-op default) is a hard error there (shared compile_context_options, ADR-037 D3). Same as the ABICHECK_AST_FRONTEND env var. |
gcc-path |
no |
— |
Path to GCC/G++ (or clang) cross-compiler binary. Applies to dump, scan, and compare mode with a single-pair (non-directory, non-package) operand — a directory/package compare rejects it with an error (same restriction as ast-frontend above). |
gcc-prefix |
no |
— |
Cross-toolchain prefix, e.g. aarch64-linux-gnu-. Applies to dump, scan, and compare mode with a single-pair (non-directory, non-package) operand — a directory/package compare rejects it with an error (same restriction as ast-frontend above). |
gcc-options |
no |
— |
Extra compiler flags passed through to the header frontend. Applies to dump, scan, and compare mode with a single-pair (non-directory, non-package) operand — a directory/package compare rejects it with an error (same restriction as ast-frontend above). |
sysroot |
no |
— |
Alternative system root directory for cross-compilation. Applies to dump, scan, deps-tree, and compare mode with a single-pair (non-directory, non-package) operand — a directory/package compare rejects it with an error (same restriction as ast-frontend above). |
nostdinc |
no |
false |
Do not search standard system include paths. Applies to dump, scan, and compare mode with a single-pair (non-directory, non-package) operand — a directory/package compare rejects it with an error (same restriction as ast-frontend above). |
follow-deps |
no |
false |
Include transitive dependency graph and symbol binding info in dump or compare output. ELF only. Applies to dump and compare modes. |
old-root |
no |
— |
Sysroot for the old (baseline) environment. Required for mode=deps-compare. |
new-root |
no |
— |
Sysroot for the new (candidate) environment. Required for mode=deps-compare. |
search-path |
no |
— |
Additional directories to search for shared libraries (space-separated). Used by deps-tree, deps-compare, and follow-deps. |
ld-library-path |
no |
— |
Simulated LD_LIBRARY_PATH (colon-separated). Used by deps-tree, deps-compare, and follow-deps. |
used-by |
no |
— |
Application binary/binaries whose actual imports/required symbol versions scope the comparison (space-separated; maps to repeated compare --used-by). The full library comparison still runs; the worst app-scoped result becomes the primary verdict/exit code, with the full verdict kept as informational context. Mutually exclusive with required-symbol/required-symbols (the CLI rejects both being set). compare mode only. |
verify-runtime |
no |
false |
With used-by: actually run each consumer binary once against the old library and once against the new one (LD_BIND_NOW=1), recording a runtime-load-failure finding when the dynamic linker reports an undefined symbol against the new library after loading cleanly against the old one. Linux-only; a no-op elsewhere. Ignored without used-by. compare mode only. |
required-symbol |
no |
— |
An exported linker symbol a plugin host resolves via dlopen/dlsym and requires (space-separated; maps to repeated compare --required-symbol). Scopes the comparison to this explicit entrypoint contract instead of the full diff. Mutually exclusive with used-by. compare mode only. |
required-symbols |
no |
— |
Path to a file of required symbols, one per line (blank lines and '#' comments ignored) -- combined with any required-symbol values. compare mode only. |
against |
no |
— |
scan mode only. Baseline artifact (a library binary or JSON snapshot) to compare the scanned new-library against. Maps to scan --against; omit for a one-build audit (see the audit input below). Overridden by abi-baseline when set. |
sources |
no |
— |
Source checkout / tree for source-intelligence analysis. The compile database is auto-discovered within it. Drives L4 source-ABI replay and L5 source-graph collection. Used by scan and dump modes, and by compare mode for the new (candidate) side only — mapped to compare's --sources new=... (the old side's evidence, if any, is expected to already be embedded in whatever old-library snapshot was resolved). |
build-info |
no |
— |
Out-of-tree L3 build context: a build directory, a compile_commands.json, or a previously-collected evidence pack. Use when the build tree lives outside --sources. Used by scan and dump modes, and by compare mode for the new (candidate) side only — mapped to compare's --build-info new=... (same old-side caveat as sources above). |
compile-db |
no |
— |
Explicit path to a compile_commands.json (scan mode; also compare mode's new side when build-info is unset). For dump mode this is folded into build-info. Use when the compile DB is not under sources. |
build-config |
no |
— |
Path to a trusted .abicheck.yml. Supplying this alone (not allow-build-query) is what permits its build.query (compile-DB generation) command to run — see allow-build-query below. Used by scan and dump modes, and by compare mode (--config). |
allow-build-query |
no |
false |
Deprecated no-op, kept only for backward compatibility — it neither grants nor restricts running build-config's build.query command (build-config alone does, per its own description above). abicheck also always runs its own inferred, abicheck-authored cmake/bazel/make compile-DB query whenever a sources input needs build context, independent of this input: pointing abicheck at a source tree is itself the request to analyse it. Used by scan and dump modes. |
depth |
no |
— |
Evidence-depth selector: binary, headers, build, or source. Used by scan and dump modes, and by compare mode (--depth). In scan mode, omit it for 'auto' (risk-driven); --depth source analyses the whole current library target unless since/changed-path seeds a narrower changed scope. Maps to --depth. (The deprecated scan-mode/source-method inputs have been removed; use depth.) |
since |
no |
— |
scan mode only. Focus the scan on files changed vs a git ref (e.g. origin/main). Maps to scan --since. |
changed-path |
no |
— |
scan mode only. Changed path(s) to focus the scan on (space-separated; alternative to since). Maps to repeated scan --changed-path. |
budget |
no |
— |
scan mode only. Time guard (e.g. 15m, 900s, 1h). The step FAILS on overflow (exit 5) — a budget never silently shrinks scope. Maps to scan --budget. |
dry-run |
no |
false |
Resolve inputs/config and print what the run would do, without performing any analysis or writing output. Exits 0 for a resolvable preview; an invocation the real run would itself reject (an invalid flag combination) still exits with that same usage error, and a requested-but-unsatisfiable depth/evidence contract still exits nonzero — a dry run validates what it can see, it does not turn every outcome into success. The one deliberate exception is this composite Action's own baseline resolution: an unresolved abi-baseline is tolerated under dry-run rather than hard-failing, since the point of a preview is to report what would be compared, not to require the comparison already be resolvable. Maps to --dry-run; supported by every mode (compare, dump, scan, deps-tree, deps-compare). For scan, this also reports the projected per-layer cost (the same preview the deprecated estimate input below used to provide). To force a scan-mode single-build hygiene lint instead of a baseline compare, simply omit against/abi-baseline for that step — scan already runs audit-only whenever no against is given (the deprecated audit input below is a functional alias for this). |
estimate |
no |
false |
Deprecated alias for dry-run (scan mode only, historical name). Setting this to true is equivalent to dry-run: 'true'. Prefer dry-run directly, which now applies to every mode, not just scan. Kept as a functional (not just accepted-and-ignored) alias for backward compatibility with existing workflows. |
audit |
no |
false |
Deprecated. scan mode only. Forces a one-build audit-only run (omits --against) even when against/abi-baseline is configured elsewhere in the workflow. Prefer simply omitting against/abi-baseline for the step instead — scan already runs audit-only whenever no against is given. Kept as a functional (not just accepted-and-ignored) alias for backward compatibility with existing workflows. |
crosscheck |
no |
— |
scan mode only. Per-check severity overrides KEY=LEVEL (off|info|warning|error), space-separated. Maps to repeated scan --crosscheck. Promote a check to =error to gate CI on it. |
risk-rules |
no |
— |
scan mode only. Path to a YAML file overriding the risk_rules profile. Maps to scan --risk-rules. |
bundle-system-providers |
no |
— |
Comma-separated extra sonames to treat as system-provided (extends the built-in libc/libstdc++/libgcc/libtbb allow-list) for the cross-library bundle-analysis layer. Maps to --bundle-system-providers on mode: compare (directory/package operands, the release/bundle comparison) and mode: scan (only meaningful with new-library-set). |
abi-baseline |
no |
— |
Automatically fetch an ABI baseline snapshot for compare mode (used as old-library) or scan mode (used as the scan baseline). Values: "latest-release" fetches *.abicheck.json from the latest GitHub Release; a tag name (e.g. "v2.0.0") fetches from that release; a file path uses the file directly. Requires GITHUB_TOKEN with contents:read permission. Overrides old-library (compare) / against (scan) when set. |
format |
no |
— |
Output format: json, sarif, html, or markdown/text (each mode's default when this input is left unset — markdown for compare/ deps-tree/deps-compare, text for scan). sarif is only supported in compare mode with a single-pair (non-directory, non-package) operand — a directory/package compare rejects it with an error. html is supported by compare (same single-pair restriction as sarif) and by deps-tree/deps-compare (a dependency-stack report). scan supports text (its default) and json only. dump ignores this input; it always writes a JSON snapshot. Requesting an unsupported format for the mode is a hard error raised before any dependency install (it used to silently fall back to a supported format with only a warning, which is unsafe for CI — see upload-sarif). Deliberately has no Action-level default (unlike most inputs): a single default here would resolve to the wrong value for scan regardless of mode, since GitHub Actions has no way to tell "left unset" from "explicitly set to the default" apart once a default is declared — each mode branch in action/run.sh supplies its own correct default instead. |
output-file |
no |
— |
Path to write the report file. If not set, output goes to stdout and job summary. |
policy |
no |
strict_abi |
Built-in policy profile: strict_abi (default), sdk_vendor, plugin_abi. |
policy-file |
no |
— |
Path to a YAML policy file with per-kind verdict overrides. |
suppress |
no |
— |
Path to a YAML suppression file to filter known/intentional changes. |
verbose |
no |
false |
Enable verbose/debug output from abicheck. |
python-version |
no |
3.13 |
Python version for setup-python. |
install-deps |
no |
true |
Deprecated — use dependency-source instead (kept for one release cycle). Ignored if dependency-source is set. true (the default) maps to dependency-source=conda-forge; false maps to dependency-source=none. |
dependency-source |
no |
— |
How to install system dependencies (castxml, gcc/g++, clang, bear): 'conda-forge' (default — this repo's pixi-managed scanner conda-forge environment, castxml 0.7.x + whichever gcc/g++ conda-forge currently resolves as default; Linux/macOS only, no clang, no bear), 'conda-forge-gcc14' (same, but pinned to gcc/g++ 14.x instead of whatever's currently default; Linux-only, no clang, no bear), 'conda-forge-clang20' (castxml + clang/clang++ 20.x instead of gcc — the one conda-forge source that provides clang, needed for L4 source-ABI replay and the clang-backed call/type/include-graph edges of L5 (the structural L5 source graph itself still builds from L3 build evidence alone, without clang); Linux/macOS, no bear), 'system' (apt/Homebrew + the pinned CastXML Superbuild — the previous default, still available; installs bear on Linux only — the macOS path installs only castxml via Homebrew and relies on Xcode's preinstalled clang, no bear), or 'none' (skip; dependencies must already be on PATH). Leave unset to fall back to install-deps for backward compatibility. On a Windows runner the unset default is 'system', not 'conda-forge' — every conda-forge source is unsupported there, so the usual default would hard-fail before analysis; an explicitly requested conda-forge* still errors rather than being silently rewritten. |
upload-sarif |
no |
false |
Upload SARIF results to GitHub Code Scanning (requires security-events: write permission). Requires format=sarif and mode=compare — setting this with any other mode or format is a hard error raised before any dependency install (mode=scan/dump/deps-tree/deps-compare never produce a SARIF report). |
fail-on-breaking |
no |
true |
Fail the step when a binary ABI break is detected (exit code 4). |
fail-on-api-break |
no |
false |
Fail the step when a source-level API break is detected (exit code 2). |
severity-preset |
no |
— |
Severity preset: 'default', 'strict', or 'info-only'. Controls exit codes and report labels. Only applies to compare mode. |
severity-addition |
no |
— |
Severity for new public API additions: 'error', 'warning', or 'info'. Set to 'error' to fail the step when additions are detected. Only applies to compare mode. |
jobs |
no |
0 |
Number of parallel library comparisons for compare mode when old-library/new-library are directories or packages. 0 = auto-detect (CPU count). Default: 0. |
extra-args |
no |
— |
Additional CLI arguments passed directly to the abicheck command. |
add-job-summary |
no |
true |
Write a markdown summary to the GitHub Actions Job Summary. Ignored for dump mode. |
pr-comment |
no |
true |
Post a sticky ABI report comment on the pull request (compare mode, including directory/package operands). The comment is a content channel and never changes the check's red/green state — breaks still gate via fail-on-breaking / fail-on-api-break. Defaults to 'true', but is a no-op unless the workflow is triggered by a pull_request event and a token with 'pull-requests: write' is available. |
pr-comment-mode |
no |
update |
'update' (default) keeps a single sticky comment and edits it in place on every run; 'new' posts a fresh comment each run. Either way the scanned head SHA is shown in the comment. |
pr-comment-on |
no |
changes |
When to comment: 'changes' (default) only comments when there is at least one ABI/API change, 'always' comments every run (including a clean "no changes" result), 'never' disables the comment. |
pr-comment-detail |
no |
standard |
Detail level of the comment body: 'summary' (verdict + counts only), 'standard' (default; per-symbol tables for breaking/review, grouped safe list) or 'full' (every change with locations, all sections expanded). |
github-token |
no |
${{ github.token }} |
Token used to post the PR comment and to auto-fetch release baselines. Defaults to the workflow token; requires 'pull-requests: write' for the comment. |