Argus

Configuration

Configuration

Argus is designed to run with no configuration at all. When you do need to shape its behaviour, there are three places to do it.

Three layers

Argus reads configuration from three sources, each suited to a different kind of decision:

  • Command-line flags tell Argus where things are and what to do this run: the POM path, the output directory, whether to publish. See Global flags.
  • The config.yml file captures durable policy: which libraries Argus may and may not touch (libraries), upgrades that must travel together (couplings), advisories to ignore, and registries to query.
  • Environment variables govern behaviour that usually belongs to the pipeline rather than the command: the validation gate, the publication budget, label conventions. See Environment variables.

The config.yml file

Since Argus 3.0 all policy lives in one schema with two ideas: a libraries entry states everything about one coordinate in one place, and a couplings entry names a wave of libraries that move together. The blocks cross-check at load time. Contradictions (a frozen library a wave tries to move, a coupled library no wave moves) are refused with an error naming the entry, rather than silently coexisting.

config.yml
# config.yml — every block is optional; an empty file (or none) is valid
version: 3

libraries:                            # per-coordinate policy
  - match: "com.acme.*"               # freeze every first-party library
    upgrade: never
  - match: "com.example:legacy-lib"   # cap at a platform-approved maximum
    max: "4.9.99"
  - match: "com.acme.platform:telemetry-starter"
    owner: acme-platform-team         # named in reports and MR copy
    upgrade: coupled                  # frozen until a coupling moves it
    delegate_transitives: true        # its transitives are the owner's problem

couplings:                            # trigger-driven waves
  - name: spring-boot 4.1 companions
    trigger: org.springframework.boot:spring-boot-dependencies
    when: ">=4.1.0"
    moves:
      - library: org.springframework.cloud:spring-cloud-dependencies
        to: ">=2025.1.2"
      - library: com.acme.platform:telemetry-starter
        to: ">=2.0"

advisory_sources:                     # which advisory databases to read; order is precedence
  - osv                               # absent or empty means [osv, config]
  - config                            # declare_advisories below; implied when the block is non-empty

ignore_advisories:                    # silence specific advisories
  - GHSA-xxxx-xxxx-xxxx

declare_advisories:                   # act on a CVE your scanner flagged that no source carries yet
  - id: CVE-2026-59083
    package: org.apache.tomcat.embed:tomcat-embed-core
    fixed: "11.0.24"
    severity: CRITICAL
    expires: 2026-12-01               # optional review date

registries:                           # where versions are discovered
  corporate:
    url: https://repo.acme.example/maven2

detection:
  governors: "on"                     # auto-import an undeclared governing BOM (default on)
  module_companions: "on"             # ADR-048 module-companion retry (default on)

Precedence

Where a flag and an environment variable cover the same ground, the flag wins. For example, --labels overrides ARGUS_LABELS, and --branch-prefix overrides ARGUS_BRANCH_PREFIX. The GitLab connection flags (--gitlab-url, --project-id, --target-branch) fall back to the matching CI_* variables when you do not pass them, which is what makes the command so short inside a pipeline.

Coming from 2.x

Argus 3.0 replaced the four 2.x policy blocks with the two above; a config that still uses them is refused at startup with an error carrying the field map. The translation is mechanical and behaviour is unchanged:

  • offlimits → a libraries entry with upgrade: never
  • ceilings → a libraries entry with max
  • delegation → owner + delegate_transitives: true on the library
  • complications → one couplings entry (allow_offlimits is implied by upgrade: coupled; suppress_transitive_remediation becomes delegate_transitives)
  • cve_ignores → top-level ignore_advisories

The libraries and couplings pages each end with a “Coming from 2.x” section covering their side of the map in detail.

Configuration reference