Configuration

config.yml: couplings

Trigger-driven waves that move companion libraries alongside a platform upgrade: the runtime couplings mvn verify cannot catch. In 3.0, couplings replace complications.

What it is for

Some upgrades cannot land alone. Bumping a Spring Boot parent to 4.1 also requires the Spring Cloud BOM at a matching release, or the application fails to start (a runtime coupling mvn verify never exercises). A coupling fires when Argus plans an upgrade of its trigger into the when range, and moves every listed library to its floor in the same merge request.

YAML

# config.yml — Argus 3.0
version: 3

libraries:
  - match: "com.acme.platform:telemetry-starter"
    owner: acme-platform-team
    upgrade: coupled                 # frozen until this wave moves it
    delegate_transitives: true

couplings:
  - name: spring-boot 4.1 companions
    trigger: org.springframework.boot:spring-boot-dependencies
    when: ">=4.1.0"                  # fires when Argus plans a Boot fix at 4.1+
    moves:
      - library: org.springframework.cloud:spring-cloud-dependencies
        to: ">=2025.1.2"            # freely managed: the wave only sets a floor
      - library: com.acme.platform:telemetry-starter
        to: ">=2.0"                 # frozen: the wave is its one exception
        add_if_missing: true

# config.yml — Argus 3.0
version: 3

libraries:
  - match: "com.acme.platform:telemetry-starter"
    owner: acme-platform-team
    upgrade: coupled                 # frozen until this wave moves it
    delegate_transitives: true

couplings:
  - name: spring-boot 4.1 companions
    trigger: org.springframework.boot:spring-boot-dependencies
    when: ">=4.1.0"                  # fires when Argus plans a Boot fix at 4.1+
    moves:
      - library: org.springframework.cloud:spring-cloud-dependencies
        to: ">=2025.1.2"            # freely managed: the wave only sets a floor
      - library: com.acme.platform:telemetry-starter
        to: ">=2.0"                 # frozen: the wave is its one exception
        add_if_missing: true

The shape of a wave

Property	Default	Description
`name` string	`—`	A label for the wave, shown in logs and merge-request copy. Required and unique.
`trigger` string	`—`	The `groupId:artifactId` whose planned upgrade fires the wave.
`when` string	`—`	The trigger version that permits the move, e.g. `">=4.1.0"`.
`moves` list	`—`	The libraries the wave carries: each a `library`, a `to` floor version, and optional `add_if_missing`.

Frozen and free companions

A companion may also name the project’s own custom <parent> POM. When the wave fires, Argus raises the <parent><version> in place (or the property it references), records the move in the report exactly like any other companion, and honours the same gates: a frozen parent needs upgrade: coupled, ceilings still cap it, and a parent already at the floor is left untouched. Version availability for the parent coordinate appears in the registry-audit/*.json files alongside every other coupling coordinate.

A single wave can move two kinds of library. A frozen library (upgrade: coupled in libraries) is otherwise never touched: the wave is its one authorised exception. A freely-managed library needs no libraries entry at all; the wave simply adds a version floor it must reach when the trigger moves. That is why couplings are their own block rather than a field on the library entry: the free companion has no frozen policy to hang off.

Coming from 2.x complications

A complications rule becomes one couplings entry.when.coordinate/reaches become trigger/when; each require becomes a moves row. The allow_offlimits flag disappears (implied by upgrade: coupled), and suppress_transitive_remediation becomes delegate_transitives on the library.