Skip to main content

Version

The version section configures how Atmos handles version management, including automatic update checking, version constraint enforcement, Atmos self-management, and Atmos-managed software versions.

Configuration​

atmos.yaml
version:
  # Pin project to a specific Atmos version
  use: "1.199.0"

  # Automatic update checking
  check:
    enabled: true
    frequency: daily

  # Version constraint enforcement
  constraint:
    require: ">=1.100.0"
    enforcement: fatal
    message: "Please upgrade Atmos to use this configuration."

  # Managed software versions
  track: prod
  lock_file: versions.lock.yaml
  providers:
    dockerhub:
      kind: docker
      url: registry-1.docker.io
  defaults:
    update:
      strategy: patch
      cooldown: 14d
  groups:
    infrastructure:
      ecosystems: [toolchain, github/actions, oci]
      update:
        strategy: minor
  tracks:
    prod:
      dependencies:
        checkout:
          ecosystem: github/actions
          package: actions/checkout
          desired: v6
          update:
            pin: sha
  dependencies:
    opentofu:
      ecosystem: toolchain
      datasource: toolchain
      package: opentofu
      desired: "~1.10"
  files:
    - manager: github-actions
      paths:
        - .github/workflows/*.yaml

Version Sections​

SectionDescription
UsePin project to a specific Atmos version
CheckAutomatic version checking and update notifications
ConstraintEnforce Atmos version requirements for your configuration
Managed VersionsManage software versions whether Atmos installs them locally or only tracks and renders them into files
ProvidersConfigure version lookup backends such as GitHub, Docker Hub, OCI registries, and ECR
DefaultsSet shared update policy, include/exclude rules, prerelease handling, and labels
GroupsBatch related version updates under shared policies
DependenciesDefine the base catalog of software versions Atmos tracks
TracksOverride catalog entries per environment or release lane
FilesConfigure file managers that render locked versions into project files
Lock FileConfigure and understand versions.lock.yaml

Environment Variables​

ATMOS_USE_VERSION
Specify which version of Atmos to use. Env var equivalent of --use-version flag.
ATMOS_VERSION_USE
Internal env var set by the --use-version flag. Highest precedence in version resolution.
ATMOS_VERSION
Convenience alias matching tfenv/goenv conventions. Lower precedence than ATMOS_VERSION_USE.
ATMOS_VERSION_CHECK_ENABLED
Enable or disable automatic version checking.
ATMOS_VERSION_ENFORCEMENT
Override version constraint enforcement level: fatal, warn, or silent.

See Also​