Version Files

version.files declares which files carry managed versions. atmos version track apply rewrites those files from the lock file, and verify fails when they drift.

Configuration

atmos.yaml

version:
  files:
    - manager: github-actions
      paths:
        - .github/workflows/*.yaml
        - .github/workflows/*.yml

    - manager: marker
      paths:
        - Dockerfile
        - scripts/**/*.sh

    - manager: template
      paths:
        - "**/*.tmpl"

When version.files is empty, managers with default paths run over those defaults.

Managers

github-actions

Rewrites uses: refs in workflow files by matching owner/repo packages.

marker

Rewrites version tokens on lines annotated with atmos:version comments.

template

Renders *.tmpl source files to sibling files using the .version context.

Updating Dockerfiles

Annotate the line to update with an atmos:version comment. The marker manager rewrites the version token in place from the lock file, matching entries by name. Given this atmos.yaml:

atmos.yaml

version:
  dependencies:
    opentofu:
      ecosystem: toolchain
      datasource: toolchain
      package: opentofu
      desired: "~1.12"

    terraform:
      ecosystem: toolchain
      datasource: toolchain
      package: terraform
      desired: "~1.15"

  files:
    - manager: marker
      paths:
        - Dockerfile

atmos version track apply prod keeps annotated lines in sync with the locked versions:

Single Tool

Dockerfile

# atmos:version opentofu
ENV TOFU_VERSION=1.12.4

Multiple Tools

A file can track more than one tool — each just needs its own marker line:

Dockerfile

# atmos:version opentofu
ENV TOFU_VERSION=1.12.4

# atmos:version terraform
ENV TERRAFORM_VERSION=1.15.6

YAML

The same annotation works in any commented format — the manager rewrites whatever token it finds on the marked line, not just Dockerfile ENV statements:

versions.yaml

tofu_version: 1.12.4 # atmos:version opentofu

Custom Match Pattern

Use match= when the default token detection is ambiguous, for example a version-shaped path segment appearing before the actual version. A trailing comment marks its own line:

Dockerfile

RUN curl -fsSL https://releases.hashicorp.com/terraform/1.15.6/terraform_1.15.6_linux_amd64.zip # atmos:version terraform match=terraform_([0-9.]+)_linux

A standalone comment on the preceding line marks the next non-blank, non-comment line instead:

Dockerfile

# atmos:version terraform match=terraform_([0-9.]+)_linux
RUN curl -fsSL https://releases.hashicorp.com/terraform/1.15.6/terraform_1.15.6_linux_amd64.zip

Updating GitHub Action Workflows

The github-actions manager rewrites uses: refs in workflow files, matching entries by owner/repo package.

Version Bump

Add a dependency for the action and register the manager:

atmos.yaml

version:
  dependencies:
    checkout:
      ecosystem: github/actions
      datasource: github-tags
      provider: github
      package: actions/checkout
      desired: "v6"

  files:
    - manager: github-actions
      paths:
        - .github/workflows/*.yaml

atmos version track apply prod rewrites the matching uses: line to the locked version:

.github/workflows/ci.yaml

steps:
  - uses: actions/checkout@v6

Pinned to SHA

Set update.pin: sha to pin third-party actions to their immutable commit SHA instead — Atmos writes the SHA with the human-readable version as a trailing comment, matching the Renovate/Dependabot convention:

atmos.yaml

version:
  dependencies:
    checkout:
      ecosystem: github/actions
      datasource: github-tags
      provider: github
      package: actions/checkout
      desired: "v6"
      update:
        pin: sha

.github/workflows/ci.yaml

steps:
  - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0

Examples

atmos version track apply prod
atmos version track apply prod --check
atmos version track apply prod --manager=github-actions