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"

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@v4
      - 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​