Skip to main content

!version

Use !version to read a locked version from the active Atmos version track.

Availability and evaluation​

Supported locations:

  • Resolved stack values: after inheritance, merging, and component template processing.
  • Skill source refs (ai.skills.<name>.ref in CLI configuration): resolved when skill sources are installed or synchronized.

Automatic evaluation requires native YAML tags from edition 2026-10-20, including unpinned projects. Quoted function strings remain literal; earlier editions retain legacy string-form behavior.

See YAML function scope for field restrictions, import timing, and native tags versus quoted strings.

The !version YAML function resolves a name from versions.lock.yaml. It uses the stack's asserted version.track, then version.track from atmos.yaml, then default.

The !version function resolves inside stack manifests and in the ref field of declarative AI skill sources. Skill refs resolve when you install or synchronize skills, rather than during configuration loading. Other fields in atmos.yaml do not accept this tag. Skill commands select the track using --track, then version.track, then default.

Usage​

!version <name>

Example​

Use !version in a stack manifest when the whole value is the version:

version:
  track: prod

components:
  terraform:
    datadog-forwarder:
      dependencies:
        tools:
          opentofu: !version opentofu
      vars:
        image:
          tag: !version dd_forwarder

With this lock file:

version: 1
tracks:
  prod:
    opentofu:
      version: 1.10.6
    dd_forwarder:
      version: 5.4.5

Atmos resolves:

dependencies:
  tools:
    opentofu: 1.10.6
vars:
  image:
    tag: 5.4.5

Embedded Strings​

Use {{ .version.name }} when the version is part of a larger string:

vars:
  image:
    uri: "public.ecr.aws/datadog/lambda-extension:{{ .version.dd_forwarder }}"

Use !version when the whole value in a stack manifest is the version. Use {{ .version.name }} when the version is part of a larger string.

Pinned Entries​

For entries with pin: digest (alias: sha) in their update policy, the two surfaces behave differently:

  • !version name always returns the version (for example, v6.1.0) — never the digest.
  • {{ .version.name }} emits the pinned form: the digest for pinned entries, the version otherwise. This is what rendered files and file managers embed.
  • {{ .version.name.Version }} and {{ .version.name.Digest }} are individually addressable when you need one specific form:
vars:
  image:
    uri: "ghcr.io/example/app@{{ .version.app.Digest }}"
    tag: "{{ .version.app.Version }}"

See Also​