Configuration

Environment variables

The settings that usually belong to the pipeline rather than the command (the validation gate, the publication budget, label conventions) are read from the environment.

Why environment variables

Some decisions are properties of where Argus runs, not of a single invocation: how strict the validation gate should be, how many merge requests a run may open, what labels your organisation tags security work with. These live naturally in CI configuration, so Argus reads them from the environment. Where a flag covers the same ground, the flag wins. See Global flags for the precedence rules.

ARGUS_* variables

Property	Default	Description
`ARGUS_VALIDATION_STRATEGY`	`compile`	The Maven gate before publication: `compile`, `test`, or `test-or-compile`. See Validation policies.
`ARGUS_VALIDATION_RETRIES`	`—`	Positive integer; retries a Maven validation that failed for an apparently transient reason.
`ARGUS_MAX_MRS`	`—`	Positive integer cap on merge requests opened per run. Unset means unlimited.
`ARGUS_RECONCILIATION_STRATEGY`	`safe`	`safe` or `reset`. Controls whether budget-deferred managed MRs may be closed. See Merge requests.
`ARGUS_PRUNE_BRANCHES`	`off`	`on` or `off`. When on, a successful reconciled run deletes Argus-owned branches that have no open merge request and whose tip commit was authored by Argus. The default, protected, desired, and human-edited branches are never touched. See Merge requests.
`ARGUS_PDF_REPORT`	`off`	`on` or `off`. When on, Argus attaches a polished, browserless PDF security report to each merge request (Maven, and npm where its early support applies) detailing every finding and how it was fixed; with `--no-publish` a combined `report.pdf` is written to the output directory. Generation is best-effort and never blocks a remediation MR. See Merge requests.
`ARGUS_EXPLOIT_INTEL`	`on`	Enriches the PDF report with exploitation intelligence: EPSS scores and CISA KEV membership. On by default; set `off`/`false`/`0`/`no` to keep the report but skip the `api.first.org` and `www.cisa.gov` feeds, for egress-controlled environments. See Network access.
`ARGUS_CEILINGS`	`on`	`on` or `off`. When on, Maven version ceilings (`libraries` `max`) in `config.yml` cap Argus remediation targets and surface any blocked advisory as residual risk. The variable keeps its pre-3.0 name for compatibility.
`ARGUS_MR_APPENDIX`	`(none)`	Path to a Markdown file whose contents are appended to the description of every merge request Argus opens, for injecting a policy notice, compliance statement, or other standing comms. Best-effort: a missing or empty file logs a warning and is skipped. Overridden by `--mr-appendix`. See Merge requests.
`ARGUS_CLEANUP_ONLY_POLICY`	`publish`	`publish` or `skip`. Whether a run that finds only stale-override cleanup work publishes it.
`ARGUS_GRAND_SLAM`	`on`	Whether aggregate remediation MRs are attempted. When on and more than one fix is pending, Argus qualifies the aggregate first and, if it passes `mvn verify`, publishes one MR and skips the per-artifact verifies (ADR-039). Set off/false/0/no to disable.
`ARGUS_FINAL_PASS`	`on`	Whether selected MR candidates and `--no-publish` local artifacts are rescanned once, given any remaining cleanup/remediation, and verified with `mvn clean verify`. Set `off`/`false`/`0`/`no` to disable.
`ARGUS_CLAIM_CHECK`	`on`	Whether each artifact is re-resolved as it will ship before publication and every advisory a plan claims to fix is checked against every module. A claim that does not hold is demoted to residual risk and the rest of the merge request still publishes; a patch that exposes an advisory the project does not carry today, or a change left fixing nothing, is withheld. Every verdict (`verified`, `demoted`, `withheld`) lands in `<out>/qualification/claim-check-<key>/result.json` and on report.json rows as `claim_check`. Runs inside the final pass. Set `off`/`false`/`0`/`no` to disable.
`ARGUS_FAILURE_ISSUES`	`on`	Whether a failing run keeps one `argus`-labelled issue in the project describing the latest failure: the error, a tail of the failing build log, the affected coordinates at their resolved versions, the dependency-graph SVG, and the evidence logs as attachments. Repeat failures rewrite the same issue; a successful run closes it. The job’s exit code is unchanged either way. Set `off`/`false`/`0`/`no` to disable. See GitLab CI/CD.
`ARGUS_MR_MOOD`	`on`	Whether merge requests, the failure issue and the comment closing an unneeded merge request open with a mood header: the Argus creature and one plain-language line (Tested and ready, Nearly there, Tidying up, Held back, Needs a hand, All clear). The header is an SVG that follows the reader’s GitLab light or dark theme, with alt text carrying the same words; if the upload fails the words are written as text. The same switch covers the rare golden owl and the “Worth a careful look” card that replaces the text caution on major version updates (the review checklist stays as markdown below it). Component input `mr_mood`. Set `off`/`false`/`0`/`no` to leave descriptions and comments as before.
`ARGUS_LABELS`	`security,argus`	Comma-separated default MR labels. Overridden by `--labels`.
`ARGUS_EXTRA_LABELS`	`—`	Comma-separated labels appended after the defaults, deduplicated.
`ARGUS_BRANCH_PREFIX`	`argus`	Source branch namespace for generated MRs. Overridden by `--branch-prefix`.
`ARGUS_COMMIT_MESSAGE_PREFIX`	`security:`	Prefix for generated commit messages. Overridden by `--commit-prefix`.
`ARGUS_CACHE_DIR`	`.argus-cache/`	Advisory cache directory. Overridden by `--cache-dir`.
`ARGUS_NPM_TEST_SCRIPT`	`npm test`	Optional package.json script name used for npm `test` qualification. Empty runs `npm test`; a value such as `ci:test` runs `npm run ci:test`. Overridden by `--npm-test-script`.
`ARGUS_ANCHOR_UPGRADE`	`on`	The anchor-upgrade pass runs by default. Set `off`/`false`/`0`/`no` to skip anchor trials and use only the classic ladder.
`ARGUS_PARENT_UPGRADE`	`on`	The direct parent-upgrade pass runs by default for vulnerable transitives. Set `off`/`false`/`0`/`no` to skip parent trials and use the classic transitive override/exclude ladder.
`ARGUS_COMPLICATIONS`	`on`	The Maven couplings pass (companion upgrades) runs by default. Set `off`/`false`/`0`/`no` to ignore the `config.yml` policy. The variable keeps its pre-3.0 name for compatibility.
`ARGUS_ANCHOR_LOG`	`anchor.log`	File path for the per-dependency anchor-upgrade reasoning and registry discovery diagnostics. Defaults to `anchor.log` next to `report.json` so the log is always available. Set to an explicit path to redirect it, or `""` to suppress the file.
`ARGUS_MAX_COMMENT_CVES`	`6`	Caps how many advisory ids an anchor-upgrade `PATCH` comment inlines in the POM; further advisories are summarised as `+N-more`. The full set always remains in the merge-request body and `report.json`, and stale-override detection is unaffected. Set `0` to inline every advisory.
`ARGUS_OTEL`	`off`	Master switch for OpenTelemetry export (metrics, logs, traces over OTLP). Explicit opt-in: org-wide `OTEL_` variables never silently enable export. Endpoint/headers come from the standard `OTEL_EXPORTER_OTLP_` variables.
`ARGUS_OTEL_EXPORTER`	`grpc`	`grpc` or `http` (OTLP/HTTP protobuf). Wins over `OTEL_EXPORTER_OTLP_PROTOCOL`.
`ARGUS_OTEL_SERVICE_NAME`	`argus`	Overrides the OTEL `service.name`; wins over `OTEL_SERVICE_NAME`.
`ARGUS_OTEL_ATTRIBUTES`	`—`	Extra resource attributes on every signal, as `k1=v1,k2=v2`. Wins per key over `OTEL_RESOURCE_ATTRIBUTES`.
`ARGUS_OTEL_ORG`	`—`	Explicit multi-tenant `org` attribute for the Grafana drill-down. Never derived from the project path; unset omits it.
`ARGUS_OTEL_METRICS`	`on`	Per-signal toggles: `ARGUS_OTEL_METRICS`, `ARGUS_OTEL_LOGS`, `ARGUS_OTEL_TRACES`.
`ARGUS_OTEL_METRICS_TEMPORALITY`	`delta`	`delta` (pair with the collector's `deltatocumulative`) or `cumulative`. See Observability.
`ARGUS_OTEL_FLUSH_TIMEOUT`	`5s`	Hard budget for the end-of-run telemetry flush; a hung collector never stalls a run beyond it.
`ARGUS_LOG_LEVEL`	`warn`	`debug`, `info`, `warn`, or `error`. Defaults `--log-level`; at `debug` the anchor and registry diagnostics include per-fetch detail.
`ARGUS_QUALIFICATION_CONCURRENCY`	`4`	Number of Maven qualification processes that may run in parallel. Set to a positive integer to fix the worker count, `1` to disable parallelism, or `-1` to auto-detect from the container's Linux cgroup CPU limit (recommended for Kubernetes runners). See Qualification concurrency.
`ARGUS_OSV_CONCURRENCY`	`8`	Number of OSV.dev advisory-hydration requests issued in parallel. The default of `8` collapses the per-advisory fetch chain on a cold cache while staying a good API citizen; OSV `429 Retry-After` responses are still honoured per request. Set to `1` behind a strict proxy or a tightly rate-limited OSV mirror.
`ARGUS_AWS_ROLE_ARN`	`—`	Optional IAM role for Argus to assume (via STS) on top of the pod's ambient EKS identity when resolving AWS Secrets Manager references. See Secrets.
`ARGUS_AWS_SECRET_ARN`	`—`	ARN of the JSON secret holding Argus' secrets; its keys back the provider-neutral `${{secret:KEY}}` reference form. Region comes from the standard `AWS_REGION`; `AWS_ENDPOINT_URL` is honoured. See Secrets.

Qualification concurrency

Argus qualifies each candidate POM by running mvn <phase> in an isolated workspace. When a remediation run produces many qualifying POMs (typically with a grand-slam strategy and a testvalidation gate), these invocations dominate total wall time. ARGUS_QUALIFICATION_CONCURRENCYcontrols how many Maven processes run in parallel (default 4).

Since 2.9.0, when grand slam is enabled Argus qualifies the aggregate of all fixes first; if it passes, the run publishes one MR and skips the per-artifact verifies entirely (ADR-039). In that common case the qualification phase is a single mvn verify, so this setting only matters on the fallback path when the aggregate does not build. On a 2-CPU runner the default of 4 oversubscribes; prefer -1 or the core count.

On Kubernetes runners, do not use runtime.GOMAXPROCS or the host CPU count as the limit. The Go runtime reads the host node's CPU count via sched_getaffinity, not the pod's CFS quota. A pod limited to 2 CPUs on a 32-core node would otherwise spawn 32 concurrent Maven JVMs, causing severe CFS throttling.

Set ARGUS_QUALIFICATION_CONCURRENCY=-1 to let Argus auto-detect the correct limit via go.uber.org/automaxprocs. This library reads the pod's cgroup CPU quota directly (cgroups v1 and v2) and uses the result as the worker count. On non-Linux hosts or outside a cgroup it falls back to the host CPU count, so -1 is safe for local development too.

Typical settings by runner type:

Kubernetes with CPU limit set: ARGUS_QUALIFICATION_CONCURRENCY=-1
Fixed-size metal runner (e.g. 8 CPUs): ARGUS_QUALIFICATION_CONCURRENCY=8
Debug / memory-constrained: ARGUS_QUALIFICATION_CONCURRENCY=1

Tokens and secrets

The GitLab token that authorises merge request creation is read from GITLAB_PRIVATE_TOKEN. It is deliberately not a flag, so it never lands in shell history or a CI command line. Store it as a masked CI variable and Argus will pick it up automatically.

GitLab CI variables

When the connection flags are absent, Argus falls back to the standard GitLab CI variables. This is what lets the command inside a pipeline be as short as argus run:

Property	Default	Description
`CI_SERVER_URL`	`https://gitlab.com`	Used when `--gitlab-url` is not passed.
`CI_PROJECT_ID`	`—`	Used when `--project-id` is not passed.
`CI_DEFAULT_BRANCH`	`main`	Used when `--target-branch` is not passed.

See GitLab CI/CD for a complete pipeline job that relies on these.