Argus

Integration

GitLab CI/CD

Argus is built to run unattended inside GitLab CI. Because its determinism makes every run reviewable, the natural home is a scheduled pipeline that opens merge requests for you.

Argus as a scheduled job

The intended deployment is simple: a scheduled CI job that runs argus run against your default branch, opens a merge request for every qualified fix, and reconciles the ones that are no longer needed. Because the same inputs always produce the same fix, you can review one example and trust the rest, which is exactly what makes unattended operation safe.

The CI/CD component

The cleanest way to adopt Argus is as a GitLab CI/CD component that you host in your own catalog. Publish it once in your CI/CD components repository, then include it from there. Set a token, add a schedule, and you are done: it downloads the binary, runs the pipeline, and publishes the reports for you. No before_script to maintain.

  1. Download argus-ci-component-4.2.1.zip (every version is on the Releases page) and extract it into your CI/CD components repository under templates/argus/.
  2. Commit it and tag a release (for example 4.2.1) so your project’s CI/CD Catalog serves the component.
  3. Include it from your own repository, replacing your-group/ci-components with the path you published it to:
.gitlab-ci.yml
include:
  # Your own components repo, where you published the Argus component (below).
  - component: $CI_SERVER_FQDN/your-group/ci-components/argus@4.2.1

stages:
  - test

Every input has a sensible default, so the snippet above already works. Override what you need (the validation gate, a publication budget, labels, the stage):

.gitlab-ci.yml
include:
  - component: $CI_SERVER_FQDN/your-group/ci-components/argus@4.2.1
    inputs:
      validation_strategy: test   # require the test suite to pass
      max_mrs: "10"               # cap MRs per run
      grand_slam: on              # aggregate compatible fixes into one MR
      anchor_upgrade: off         # optional: use only the classic ladder
      extra_labels: "team-platform"
      stage: security

stages:
  - security
Download the CI/CD componentView the release page

Or: a raw pipeline job

If you would rather not use the component, a plain job works too. It needs an image with your JDK and Maven, because Argus shells out to mvn to build the SBOM and qualify patches. Download the prebuilt binary in a before_script step (no compiling), and then the job is a single command. A ready-to-copy version is shown below.

.gitlab-ci.yml
security:argus:
  stage: security
  image: maven:3.9-eclipse-temurin-21
  variables:
    ARGUS_VERSION: "4.2.1"
    ARGUS_VALIDATION_STRATEGY: "compile"
    ARGUS_MAX_MRS: "10"
  before_script:
    # Download the prebuilt binary for the runner's architecture
    - curl -fsSL -o /usr/local/bin/argus
        "https://argus-assets.typecheck.io/v${ARGUS_VERSION}/argus-${ARGUS_VERSION}-linux-amd64"
    - chmod +x /usr/local/bin/argus
  script:
    - argus run
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

The token

Opening merge requests needs a token with API access, supplied in GITLAB_PRIVATE_TOKEN. Store it as a masked, protected CI/CD variable, never in the repository. A project access token or a bot account works well, since the merge requests will be attributed to whatever identity the token belongs to.

Argus 4.0.0 no longer reads the project’s vulnerability report, so the token needs no scope beyond branches and merge requests. A config.yml that still lists the removed gitlab advisory source refuses to load until the entry is deleted.

Scheduling

Add a pipeline schedule so the job runs on a cadence. Weekly is a sensible starting point. The rules in the job above restrict Argus to scheduled pipelines, so it never runs on ordinary pushes:

schedule
# Settings → CI/CD → Pipeline schedules → New schedule
# e.g. "0 6 * * 1" runs every Monday at 06:00

When a run fails

A failing Argus run fails its CI job, exactly as any other job would: the exit code is unchanged, and nothing about the pipeline result depends on the reporting below.

On top of that, Argus keeps one issue in the project describing the latest failure, so a broken run is visible to the people who own the repository without anyone opening job logs. The issue carries the error, an inline tail of the failing build log, which dependencies are affected and at which resolved versions, the same dependency-graph picture the merge requests embed, and the full evidence logs and scan report as attachments.

It is one issue per project, not one per run. A project that fails every night for a month has a single issue, rewritten each time with the latest failure. Argus finds its own issue by the argus label and its title, and never touches issues it did not raise. When a later run succeeds, that issue is closed: an open failure issue on a project that has recovered is worse than none.

Tuning the run

A few variables shape how a scheduled run behaves. ARGUS_MAX_MRS caps how many merge requests a single run opens, so the first run against a long-neglected project does not flood your review queue. ARGUS_VALIDATION_STRATEGY chooses how hard Maven must work before publishing. ARGUS_LABELS and ARGUS_EXTRA_LABELS align the merge requests with your triage workflow. See Merge requests for how the merge requests are organised, and Validation policies for the gate.

Anchor upgrades are on by default: Argus can fix a transitive vulnerability by upgrading the BOM, parent, or managed library that governs it, re-scanned and mvn verify-gated, with the override ladder as the fallback. The component also writes anchor.log as an artifact by default. To discover versions from a private registry rather than Maven, commit a config.yml and add its credentials as masked CI/CD variables. See Anchor upgrades.