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
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 matchingowner/repopackages. marker- Rewrites version tokens on lines annotated with
atmos:versioncomments. json- Writes locked values into JSON files at configured field paths, preserving formatting and key order.
yaml- Writes locked values into YAML files at configured field paths, preserving comments, anchors, and key order.
template- Renders
*.tmplsource files to sibling files using the.versioncontext.
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 version track apply prod keeps annotated lines in sync with the locked versions:
- Single Tool
- Multiple Tools
- YAML
- Custom Match Pattern
A file can track more than one tool — each just needs its own marker line:
The same annotation works in any commented format — the manager rewrites whatever token it finds on the marked line, not just Dockerfile ENV statements:
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:
A standalone comment on the preceding line marks the next non-blank, non-comment line instead:
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 version track apply prod writes the resolved value at the configured path:
- Single Field
- Multiple Fields
- Reshaping the Value
Only the version value's bytes change — every other key, its ordering, and any unusual spacing in the file is preserved exactly.
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:
A dependency sourced from github-releases/github-tags locks the raw git tag (e.g. v2.5.0). When a target field needs a different shape, add format to the set entry: a Go template (Sprig plus Atmos's template functions) rendered against the resolved version, whose output replaces the verbatim value:
Without format, the same rule would write "version": "v2.5.0" verbatim.
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.
format is optional. When omitted, the resolved value is written verbatim (today's default behavior). When set, it's a Go template rendered against the resolved version — .Version (the human-readable version), .Digest, and .Pin are all available in the template context — and the rendered string is written instead. Any string function from Sprig works, e.g. trimPrefix, trimSuffix, replace, or regexReplaceAll.
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
-1segment) — there's no way to tell "already applied" from "not yet applied" by reading the array back, so everyapplywould append another element forever. - A
pathwhose 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, notengines). - Two
setentries targeting the samepath— the second write would otherwise silently discard the first. - A
formattemplate that fails to parse or execute (a syntax error, or a reference to a field that doesn't exist) — rejected outright rather than writing garbage or an empty string.
Updating YAML Files
The yaml manager writes locked values into YAML files at configured field paths, using the same format-preserving editor behind atmos config set and atmos stack set. It edits the document via a targeted assignment rather than a full unmarshal/remarshal, so comments, anchors and aliases, and key order on untouched fields survive the write.
atmos version track apply rewrites the configured field and leaves everything else — comments, anchors, unrelated keys — untouched:
path uses the same dot-notation as atmos config set/atmos stack set: dots nest into maps, [N] indexes into a sequence (e.g. sources[0].version), and a key that isn't a simple identifier is quoted (metadata."weird.key"). This differs from the json manager's sjson/gjson dialect — the two managers don't share path syntax.
format works exactly as it does for the json manager: an optional Go template rendered against the resolved version (.Version, .Digest, .Pin), with the rendered string written instead of the verbatim value. See Sprig for the available string functions.
A simple path that doesn't exist yet in the document is created rather than rejected. A path whose current value is a map or list is rejected rather than silently replaced with a scalar — target the specific field inside it instead.
Because the editor re-encodes the document, indentation is normalized to the file's own detected width rather than preserved byte-for-byte the way the json manager's sjson patch is — the practical difference shows up only in edge cases (unusual mixed indentation, some flow-style collections), not in ordinary block-style YAML.
Updating GitHub Action Workflows
The github-actions manager rewrites uses: refs in workflow files, matching entries by owner/repo package.
- Version Bump
- Pinned to SHA
Add a dependency for the action and register the manager:
atmos version track apply prod rewrites the matching uses: line to the locked version:
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:
Examples
atmos version track apply prod
atmos version track apply prod --check
atmos version track apply prod --manager=github-actions
