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: json
      paths:
        - agent-skills/.claude-plugin/plugin.json
        - .claude-plugin/marketplace.json
      options:
        set:
          - path: version
            from: atmos

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

When version.files is omitted, managers with default paths run over those defaults. An explicit files: [] is different from omitting the key: it means "manage zero files," and suppresses the default-path fallback.

version.files, like every other atmos.yaml setting, follows Atmos's standard import precedence: the main atmos.yaml's own value always wins over an import: fragment or atmos.d/ file that also sets version.files, including files: []. An imported fragment can only supply version.files when the main file doesn't mention the key at all — it can never override or clear a list the main file already declares.

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.

json

Writes locked values into JSON files at configured field paths, preserving formatting and key order.

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 JSON Files

The json manager writes locked values into JSON files at configured field paths, using sjson/gjson dot-path syntax. Unlike a full JSON parse and re-serialize, sjson patches only the targeted field and leaves the rest of the file's bytes — formatting, key order, whitespace — untouched.

atmos.yaml

version:
  dependencies:
    atmos:
      ecosystem: github/actions
      datasource: github-releases
      provider: github
      package: cloudposse/atmos
      desired: "~1.160"

  files:
    - manager: json
      paths:
        - agent-skills/.claude-plugin/plugin.json
      options:
        set:
          - path: version
            from: atmos

atmos version track apply prod writes the resolved value at the configured path:

Single Field

agent-skills/.claude-plugin/plugin.json

{
  "name": "atmos",
  "version": "1.160.0",
  "license": "Apache-2.0"
}

Only the version value's bytes change — every other key, its ordering, and any unusual spacing in the file is preserved exactly.

Multiple Fields

A file can have more than one managed field — each just needs its own set entry, and a rule can list more than one target file:

atmos.yaml

  files:
    - manager: json
      paths:
        - package.json
      options:
        set:
          - path: version
            from: cli
          - path: engines.node
            from: node

package.json

{
  "name": "example",
  "version": "2.5.0",
  "engines": {
    "node": "20.11.0"
  }
}

path follows sjson/gjson dot syntax: dots nest into objects, a bare number indexes into an array, and a literal dot inside a key name is escaped as \.. path is always a YAML string — quote numeric segments (path: "0"), or the value decodes as a YAML integer and fails validation.

A simple path (no wildcards) that doesn't exist yet in the file is created rather than rejected, so double-check path for typos — a misspelled path silently adds a new field instead of updating the intended one. Wildcard/query paths (items.#.version, *, ?, @) update every matching location when the path resolves against the current document, but error instead of silently doing nothing when it resolves to nothing — for example, an empty array or a missing parent key.

A few configurations are rejected outright rather than risking silent data loss:

• Array-append paths (any -1 segment) — there's no way to tell "already applied" from "not yet applied" by reading the array back, so every apply would append another element forever.
• A path whose current value is an object or array — writing a scalar there would silently discard the whole subtree. Target the specific field inside it instead (engines.node, not engines).
• Two set entries targeting the same path — the second write would otherwise silently discard the first.

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