CLI reference¶
Both GitHub surfaces drive the same chargate CLI. Exit codes: 0 pass ·
1 blocking net-new findings · 2 setup/usage error.
chargate <filter-sarif | ci | sbom | local | install-hooks | uninstall-hooks | version> [options]
chargate filter-sarif¶
The pure net-new filter: a SARIF report + a base/head → filtered SARIF + counts + a gate exit code. Decoupled from GitHub Actions and unit-tested in isolation.
This subcommand and the counts JSON it writes are a stable public interface for
other tools: the counts document carries a schema_version, and a consumer must
hard-fail on a version it does not recognise rather than gate on a document it cannot
read. Key-by-key contract, invariants, and the exit codes a consumer must distinguish:
Consuming the output.
chargate filter-sarif --sarif report.sarif --base "$BASE" --head "$HEAD" \
--out net-new.sarif --counts-json counts.json --fail-on any
| Flag | Default | Purpose |
|---|---|---|
--sarif |
(required) | Path to the full SARIF report. |
--base |
(required) | Base ref/SHA (PR target). |
--head |
HEAD |
Head ref/SHA. |
--repo |
. |
Path to the git repository. |
--precision |
line |
Net-new precision: line or file. |
--no-location-policy |
ignore |
Treatment of results with no file location: ignore (never block) or block. |
--no-region-fallback |
off | Disable file-level fallback for changed-file results lacking a startLine. |
--no-sops-ignore |
off | Gate on secret-scanner hits even on SOPS-encrypted values (ENC[AES256_GCM,...]). By default these are dropped as false positives, see Net-new gating. |
--strip-prefix |
(none) | Path prefix to strip from SARIF URIs before matching (repeatable). |
--no-merge-base |
off | Diff base..head directly instead of merge-base(base, head)..head. |
--out / --full-out / --counts-json |
(none) | Write the net-new SARIF / a copy of the full SARIF / counts JSON. |
--fail-on |
any |
Severity threshold that blocks: any\|critical\|high\|medium\|low\|none. |
--no-gate |
off | Always exit 0 (report only). |
--quiet |
off | Suppress the human summary. |
chargate ci¶
The full CI flow: run MegaLinter, preserve the full SARIF, gate on net-new (PR events only), and optionally ship to the sinks (DefectDojo / Dependency-Track). Each sink is active iff its host/URL flag is set.
chargate ci --mode auto --flavor all --sarif-out full.sarif
Every image-selection flag also reads a CHARGATE_* env var when the flag is
omitted (CHARGATE_MEGALINTER_REGISTRY, CHARGATE_MEGALINTER_REGISTRY_FALLBACK,
CHARGATE_MEGALINTER_PULL_TIMEOUT, CHARGATE_MEGALINTER_NAMESPACE,
CHARGATE_MEGALINTER_IMAGE, CHARGATE_MEGALINTER_TAG, CHARGATE_DOCKER_PLATFORM,
CHARGATE_ARCH_STRATEGY, CHARGATE_JOBS), so a self-hosted runner fleet can point
every repo at an internal mirror without editing any workflow. Explicit flag beats
env var beats built-in default.
A mirror that fails falls back to ghcr.io. When the registry is anything other
than ghcr.io (a mirror or pull-through cache), Chargate pulls each image itself
before docker run and gives the registry --megalinter-pull-timeout seconds
(default 300). If that pull fails for any reason (unreachable, timed out, manifest
unknown, auth error), it logs one ::warning:: and pulls the same image from
ghcr.io/oxsecurity instead, so a cache outage costs a slower pull rather than every
job on the runner pool. After the first failure the rest of the run skips the mirror.
An image already on the Docker daemon is used as-is, and --megalinter-image is never
rewritten. If ghcr.io fails too, the error names both failures and the run exits
2 (in standalone mode only that linter is lost, as when its container dies).
Set CHARGATE_MEGALINTER_REGISTRY_FALLBACK=false on runners that must never pull from
the public registry: Chargate then skips its own pull and fails at docker run, as it
did before the fallback existed. Any value other than true or false exits 2
rather than guessing.
Key flags beyond the shared filter options:
| Flag | Default | Purpose |
|---|---|---|
--mode |
auto |
auto (from GITHUB_EVENT_NAME), pr (net-new gate), or baseline (no gate). |
--sarif |
(none) | Use an existing SARIF instead of running MegaLinter. |
--flavor |
all |
MegaLinter flavor (all = full image), or quality — a five-linter set chargate curates, with no upstream image, so it always runs standalone. See The quality flavor. |
--megalinter-tag |
v10.0.0 |
MegaLinter image tag, or a sha256:… digest to pin. |
--megalinter-registry |
ghcr.io |
Registry host. Docker Hub is frozen at v9.4.0, so it cannot serve v9.5.0+. |
--megalinter-registry-fallback |
true |
true\|false. When the registry is not ghcr.io and cannot serve an image, pull it from ghcr.io instead. false fails at the pull. |
--megalinter-pull-timeout |
300 |
Seconds a non-ghcr.io registry gets to deliver an image before the fallback. |
--megalinter-namespace |
oxsecurity |
Image namespace (set for a mirror / pull-through cache). |
--megalinter-image |
(none) | Full image reference, overriding registry/namespace/flavor/tag entirely. |
--docker-platform |
(none) | Value for docker run --platform (e.g. linux/amd64 to force emulation). |
--arch-strategy |
auto |
auto (flavor image on amd64, per-linter images on arm64) · flavor · standalone · fail. |
--standalone-linter |
(none) | Linter key for standalone mode (repeatable). Default: the flavor's SARIF-emitting set. |
--jobs |
4 |
Standalone mode: concurrent linter containers. |
--enable-linter / --disable-linter |
(none) | Toggle a linter (repeatable). |
--incremental |
off | PR/gate mode only. Runs MegaLinter over just the files changed vs the base (VALIDATE_ALL_CODEBASE=false) instead of the whole repo. The net-new gate still uses chargate's own diff, so this changes scan cost, not the verdict. |
--default-branch |
"" |
Base branch for incremental change detection. Sets MegaLinter's DEFAULT_BRANCH. |
--sarif-out / --filtered-out / --counts-json |
(none) | Write the full / net-new / counts outputs. The action always passes all three; the last two are the documented consumer interface. |
--strict |
off | Fail the job if MegaLinter itself errors. (A SARIF with no runs fails without it, see architecture.) |
--defectdojo-url |
(none) | DefectDojo base URL (enables import of the full SARIF). |
--defectdojo-token-env |
DEFECTDOJO_TOKEN |
Env var holding the DD API token. |
--dd-product / --dd-engagement / --dd-engagement-id |
(none) | DefectDojo targeting. |
--dd-product-type |
(none) | DefectDojo product type name. Required only when the product does not exist yet and has to be auto-created. |
--dd-test-title |
(none) | Title for the DefectDojo test. |
--dd-tag |
(none) | Tag to attach to the import. Repeatable. |
--dd-import / --dd-no-close-old / --dd-insecure |
off | Use import (not reimport) / keep old findings / skip TLS verify. |
--dependency-track-url |
(none) | Dependency-Track base URL (enables CycloneDX BOM upload). |
--dt-api-key-env |
DEPENDENCYTRACK_API_KEY |
Env var holding the DT API key. |
--bom |
(none) | Path to the CycloneDX BOM to upload (the action generates this with Syft). |
--dt-project-name / --dt-project-version / --dt-project-uuid |
(none) | Dependency-Track project targeting. |
--dt-parent-name / --dt-parent-version |
(none) | Parent project, when you keep Dependency-Track projects in a hierarchy. |
--dt-no-auto-create / --dt-is-latest / --dt-insecure |
off | Don't auto-create the project / mark latest / skip TLS verify. |
--dt-project-tag |
(none) | Dependency-Track project tag, repeatable. A repo:<name> tag is the join key for grouping a repo's projects. |
--pr-comment |
off | Post GHAS-style PR comments for net-new findings (PR/gate mode only). |
--pr-number / --repo-slug |
(none) | Pull request number and owner/repo to comment on. |
--github-token-env |
GITHUB_TOKEN |
Env var with a token that has pull-requests: write. |
--pr-comment-mode |
both |
summary (one updatable comment), inline, or both. |
--pr-comment-max-inline |
50 |
Cap on inline comments; the rest stay in the summary. |
--pr-comment-insecure |
off | Skip TLS verification for the GitHub API (GHES testing). |
PR comments are net-new only and failure-isolated: a GitHub API error is logged and
never changes the gate outcome. The host action sets --pr-number / --repo-slug
from the event and honors GITHUB_API_URL for GHES.
chargate sbom¶
Ship a CycloneDX BOM to Dependency-Track on its own — no MegaLinter, no SARIF, no gate. Seconds, not the ~15 minutes a scan costs.
chargate ci already carries the BOM sink, but only fires it on non-PR events:
a BOM per pull request would litter Dependency-Track with throwaway N/merge
project versions. A consumer whose gate runs on pull_request only — the usual
shape, because a full scan on every merge is the most expensive thing in CI — never
reaches that path, so the repo never appears in Dependency-Track at all. This
subcommand is that missing push-time path standing alone.
chargate sbom \
--dependency-track-url https://dtrack.example.com \
--bom sbom.cdx.json \
--dt-project-name "$GITHUB_REPOSITORY" \
--dt-project-version main
It takes the same Dependency-Track flags as chargate ci (--dependency-track-url,
--dt-api-key-env, --bom, --dt-project-*, --dt-parent-*, --dt-no-auto-create,
--dt-is-latest, --dt-insecure) plus:
| Flag | Default | Meaning |
|---|---|---|
--strict |
off | Treat a Dependency-Track upload failure as fatal (exit 2). |
--quiet |
off | Suppress the human summary. |
Exit policy is the inverse of the sink-on-a-gate rule, deliberately. A
misconfigured sink — no URL, no project, no API key, no BOM file — exits 2.
This command exists only to upload, so "nothing to upload to" is a broken job, not
a sink someone switched off; silence in exactly that case is what let a whole org's
repos go missing from Dependency-Track unnoticed. A Dependency-Track outage stays
failure-isolated (warn, exit 0) unless --strict, so a server that is merely down
cannot turn every repo's CI red.
On success it writes the project link to the job summary and to a
dependency_track_url action output.
chargate local¶
Fast staged-file checks for pre-commit (gitleaks + ruff, each skipped if the tool is absent). A first line, deliberately narrower than the full CI net.
chargate local path/to/file.py # pre-commit passes the staged files
chargate local # no args -> checks staged files
chargate install-hooks¶
Wire Chargate's git hooks into every repo globally, using the
pre-commit framework (which must be installed). It
generates pre-commit + pre-push + commit-msg dispatchers pointed at a global
~/.pre-commit-config.yaml, sets core.hooksPath (so the hooks apply to existing
repos immediately) and init.templateDir (so new clones inherit them).
chargate install-hooks # refuses to clobber a hand-maintained config
chargate install-hooks --force # overwrite a non-chargate ~/.pre-commit-config.yaml
Chargate's hooks live inside a regenerated >>> chargate-managed >>> block; any
repos you add outside that block are preserved on reinstall. Installed via Homebrew,
brew install calebsargeant/tap/chargate brings pre-commit along. See
Setup → Global hook install for the full
walkthrough.
chargate uninstall-hooks¶
Revert install-hooks, restoring (or unsetting) the prior global core.hooksPath
and init.templateDir.
chargate uninstall-hooks
chargate version¶
Prints the chargate version (also chargate --version).