Skip to main content

Version Pinning

Pin your project to a specific Atmos version using version.use in atmos.yaml. When configured, Atmos automatically downloads the specified version (if not already installed) and re-executes itself, ensuring everyone on your team uses the same version.

Configuration​

atmos.yaml
version:
  use: "1.199.0"

When any atmos command runs, it will:

  1. Check if the requested version is already installed
  2. Download and install it automatically if needed
  3. Re-execute the command with the correct version

Versions are cached in ~/.atmos/bin/cloudposse/atmos/{version}/.

Supported Version Formats​

Exact semver

A specific release version (e.g., 1.199.0). This is the recommended format for production use.

version:
  use: "1.199.0"
latest

Resolves to the latest available release from GitHub.

version:
  use: "latest"
pr:<number>

Install from a pull request's build artifacts. Useful for testing changes before they are released.

version:
  use: "pr:1234"
sha:<hash>

Install from a specific commit's build artifacts.

version:
  use: "sha:ceb7526"
ref:<name>

Install from the latest commit of a branch or tag, using that commit's CI build artifacts. The ref is resolved to its current commit on every run, so a mutable branch like main always tracks the latest build; the resolved commit is cached, so unchanged refs do not reinstall.

version:
  use: "ref:main"        # latest main build

Accepts branch names, tag names, and slash-qualified refs:

atmos --use-version=ref:main             # branch
atmos --use-version=ref:release/v1.199    # branch with a slash
atmos --use-version=ref:v1.199.0          # tag (the tag's commit artifact, not the release)
atmos --use-version=ref:heads/main        # explicit branch (disambiguation)
atmos --use-version=ref:tags/v1.199.0     # explicit tag (disambiguation)

Like pr: and sha:, this installs CI build artifacts (retained for 90 days), not released binaries. For an older tag whose artifacts have expired, use the plain semver form (e.g. 1.199.0) to install the release instead.

Command-Line Override​

Override the configured version for a single command using the --use-version flag:

atmos --use-version 1.201.0 terraform plan -s mystack

Precedence​

Version sources are evaluated in this order (highest to lowest priority):

PrioritySourceExample
1--use-version flagatmos --use-version 1.201.0 terraform plan
2ATMOS_VERSION_USE env varATMOS_VERSION_USE=1.201.0 atmos terraform plan
3ATMOS_VERSION env varATMOS_VERSION=1.201.0 atmos terraform plan
4version.use in atmos.yamlversion: use: "1.199.0"

The --use-version flag and ATMOS_USE_VERSION env var both set ATMOS_VERSION_USE internally, so they share the same priority level.

Environment Variables​

ATMOS_USE_VERSION

Specify which version of Atmos to use. This is the env var equivalent of the --use-version flag. Internally, it feeds the flag value which sets ATMOS_VERSION_USE.

ATMOS_USE_VERSION=1.199.0 atmos terraform plan -s mystack
ATMOS_VERSION_USE

The internal env var checked directly by the version resolution logic. Set automatically by the --use-version flag and ATMOS_USE_VERSION. Can also be set directly for highest precedence.

ATMOS_VERSION_USE=1.199.0 atmos terraform plan -s mystack
ATMOS_VERSION

Convenience alias matching conventions used by tools like tfenv and goenv. Lower precedence than ATMOS_VERSION_USE.

export ATMOS_VERSION=1.199.0

Examples​

Pin Project to a Specific Version​

atmos.yaml
version:
  use: "1.199.0"

Environment-Specific Versions with Profiles​

Use profiles to specify different versions per environment:

profiles/dev/atmos.yaml
version:
  use: "1.201.0"  # Latest version for development
profiles/prod/atmos.yaml
version:
  use: "1.199.0"  # Stable version for production

Activate a profile:

atmos --profile dev terraform plan -s mystack

# Or via environment variable
ATMOS_PROFILE=prod atmos terraform apply -s mystack

CI/CD Pipelines​

Pin the version in your CI environment:

.github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ATMOS_VERSION: "1.199.0"
    steps:
      - uses: actions/checkout@v6
      - name: Deploy
        run: atmos terraform apply -s production/mystack --auto-approve

Combined with Version Constraints​

Use version.use to pin the version and version.constraint to enforce a minimum across the team:

atmos.yaml
version:
  use: "1.199.0"
  constraint:
    require: ">=1.100.0"
    enforcement: fatal

See Also​