cloudposse/atmos v1.206.3-rc.1

on GitHub

• Extend --use-version flag to support PR numbers using the pr:NNNN format (e.g., --use-version pr:2038) or auto-detected all-digit format (--use-version 2038)
• Enable users to test Atmos features from PRs by automatically downloading and installing build artifacts from successful CI runs
• Add smart GitHub token detection with multiple fallback strategies (ATMOS_GITHUB_TOKEN, GITHUB_TOKEN, gh CLI)
• Implement TTL caching (1 minute) to minimize GitHub API calls when repeatedly using PR versions
• Add semver validation for --use-version flag to provide clear error messages for invalid inputs
• Provide clear, actionable error messages for common failure scenarios (missing token, failed CI, unsupported platforms, invalid version format)

why

• Testing PR features currently requires installing Go, running go install (which has proxy issues), or manually downloading artifacts from GitHub Actions UI
• This friction prevents contributors and users from easily validating changes before merge
• Enabling PR artifact installation via --use-version makes testing as simple as atmos --use-version 2038 terraform plan
• Supports the same workflow users already know with version management, but extended to PRs
• Semver validation prevents confusing silent failures when users typo version strings

Usage

# Explicit PR prefix
atmos --use-version pr:2040 version

# Auto-detected PR (all digits)
atmos --use-version 2040 version

# Valid semver
atmos --use-version 1.175.0 version

# Invalid format - now errors with helpful message
atmos --use-version abc version
# ✗ Error: invalid version format 'abc'
#   💡 Version must be a PR number, pr:NNNN, or semver (e.g., 1.2.3)

Test plan

• Test valid PR: ./build/atmos --use-version 2040 version
• Test invalid PR: ./build/atmos --use-version 999999 version (should error)
• Test TTL caching: run twice within 1 minute
• Test invalid format: ./build/atmos --use-version abc version (should error)
• Test invalid format: ./build/atmos --use-version abc123 version (should error)
• Test semver: ./build/atmos --use-version 1.175.0 version (should work)

references

• New packages:
  • pkg/github/artifacts.go - GitHub API integration for PR artifact retrieval
  • pkg/github/token.go - Smart token detection with gh CLI fallback
  • toolchain/pr_artifact.go - PR artifact download and installation logic
  • toolchain/version_spec.go - Version format parsing and validation
• Modified packages:
  • pkg/version/reexec.go - PR version detection in version switching
• Test coverage: Unit tests for all new functionality

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Install Atmos from PR artifacts (pr:NNNN) and SHAs via --use-version with platform-aware downloads, local caching, TTL checks, safe extraction, and progress indicators
  • Improved version spec parsing and explicit --use-version re-exec handling
  • Automatic GitHub token detection (env vars then gh CLI) and clearer, actionable error messages for auth/CI/platform issues

• Documentation

  • Added guide for PR/SHA artifact installation, authentication, and troubleshooting

• Tests

  • Extensive unit tests covering artifact retrieval, token handling, caching, extraction, and install flows

why

• Extend the existing multi-cloud auth framework to GCP, matching AWS/Azure patterns.
• Provide secure CI/CD via WIF (no long-lived keys).
• Enforce consistent, provider-scoped file isolation aligned with the universal pattern (AWS reference).
• Ensure auth whoami works for GCP credential types that don’t implement validation yet.

references

• Universal auth file isolation pattern: docs/prd/auth-file-isolation-pattern.md
• AWS reference implementation: docs/prd/aws-auth-file-isolation.md
• Azure isolation plan (consistency target): docs/prd/azure-auth-file-isolation.md
• GCP provider/identity docs updated in website/docs/cli/configuration/auth/*

p.s. tested locally and in GitHub with WIF

Summary by CodeRabbit

• New Features

  • First-class GCP auth: ADC and Workload Identity Federation providers, Service Account and Project identities, GCPCredentials type, provider-scoped credential files, env helpers, static token via GOOGLE_OAUTH_ACCESS_TOKEN, auth-realm resolution, and pluggable provider/identity factory; keyring now stores GCP creds.

• Bug Fixes

  • Validate fallback for NotImplemented to accept unexpired creds; clearer whoami error guidance for GCP reauthentication scenarios.

• Documentation

  • New GCP docs, examples, blog post and roadmap update.

• Tests

  • Extensive unit tests for GCP flows, files, factories, providers, identities and credentials.

• Fixed three interconnected bugs that prevented templates.settings.env from propagating environment variables to gomplate datasources
• mapstructure:"-" tag on TemplatesSettings.Env silently dropped the env field during the encode/decode/merge pipeline in ProcessTmplWithDatasources
• Viper lowercased env var keys (e.g., AWS_PROFILE → aws_profile) and caseSensitivePaths didn't include templates.settings.env
• Stack manifest env vars were dropped at 4 caller decode sites in utils.go and describe_stacks.go
• Added deferred env cleanup to restore original env values after template processing, preventing pollution across components
• Updated dependency compatibility (gocloud.dev, terraform-exec) after go.mod update

why

• Users configuring templates.settings.env with AWS credentials (e.g., AWS_PROFILE, AWS_REGION) expected gomplate datasources (S3, SSM, Secrets Manager) to use those credentials, but env vars were never set in the OS environment
• The os.Setenv loop in ProcessTmplWithDatasources never executed because templateSettings.Env was always nil after mapstructure dropped it
• Without env cleanup, env vars set for one component could leak into subsequent component processing

references

• Closes #2083
• Fix document: docs/fixes/2026-02-16-gomplate-datasource-env-vars.md

Summary by CodeRabbit

• Bug Fixes

  • Fixed environment variable propagation in template datasources—vars from config and stack manifests are preserved during template processing.
  • Improved case sensitivity handling for template environment variables.
  • Removed an unnecessary debug log line.

• New Features

  • Terraform workspace selection accepts optional parameters.

• Documentation

  • Added docs describing datasource environment variable propagation and the fix.

• Tests

  • Added integration and unit tests covering env propagation and case sensitivity.

• Chores

  • Updated dependency licenses/versions and NOTICE entries.
  • Component describe outputs now include a new deprecated field placeholder.

• Add Ansible as a first-class component type in Atmos, alongside Terraform, Helmfile, and Packer
• Implement atmos ansible playbook command to execute Ansible playbooks with stack-based configuration
• Implement atmos ansible version command to display Ansible version information
• Add stack processor support for Ansible components with full inheritance, vars, env, settings, and auth sections
• Support automatic variable file generation passed to Ansible via --extra-vars @<varfile>
• Enable pass-through of native Ansible flags via -- separator
• Add command aliases: an for ansible, pb for playbook
• Include comprehensive documentation in Docusaurus

why

• Ansible is widely used for configuration management and application deployment, complementing Terraform's infrastructure provisioning
• Users can now manage Ansible playbooks with the same stack-based configuration patterns they use for Terraform
• Enables consistent variable management across infrastructure (Terraform) and configuration (Ansible) layers
• Supports the same powerful features as other component types: inheritance, environment variables, settings, JIT provisioning, and validation
• Reduces context-switching by providing a unified CLI for infrastructure orchestration

usage

Configuration

Add to atmos.yaml:

components:
  ansible:
    base_path: "components/ansible"
    command: "ansible-playbook"      # optional
    auto_generate_files: false       # optional

Stack Manifest

Define Ansible components in stack manifests:

components:
  ansible:
    webserver:
      vars:
        app_name: myapp
        app_port: 8080
        app_version: "1.0.0"
      env:
        ANSIBLE_HOST_KEY_CHECKING: "false"
      settings:
        ansible:
          playbook: site.yml
          inventory: inventory/production

Commands

# Show Ansible version
atmos ansible version

# Run playbook with settings from stack manifest
atmos ansible playbook webserver --stack prod

# Specify playbook explicitly (overrides stack settings)
atmos ansible playbook webserver -s prod --playbook deploy.yml

# Specify both playbook and inventory
atmos ansible playbook webserver -s prod -p site.yml -i hosts.ini

# Dry run (shows commands without executing)
atmos ansible playbook webserver -s prod --dry-run

# Pass native Ansible flags via -- separator
atmos ansible playbook webserver -s prod -- --check
atmos ansible playbook webserver -s prod -- --verbose --limit "web01,web02"
atmos ansible playbook webserver -s prod -- --tags "deploy,config"

# Use aliases for brevity
atmos an pb webserver -s prod

# Path-based component resolution
cd components/ansible/webserver
atmos ansible playbook . -s prod

Environment Variables

ATMOS_ANSIBLE_PLAYBOOK=site.yml      # Default playbook
ATMOS_ANSIBLE_INVENTORY=hosts.ini    # Default inventory

references

• Ansible Documentation
• ansible-playbook CLI Reference

Summary by CodeRabbit

• New Features

  • Native Ansible support: new ansible command with playbook/version subcommands, --playbook/-p and --inventory/-i flags, passthrough of native Ansible options, shell completions, provider-backed execution, JIT component provisioning, automatic varfile generation/cleanup, and env/stack-aware execution.

• Documentation

  • New CLI docs, usage pages, examples, blog post, and roadmap entry for Ansible workflows.

• Tests

  • Extensive unit and integration tests covering CLI, flags, completions, provider, executor, and stack processing.

• Chores

  • Added Ansible config keys/paths, help aliases/snapshots, and user-facing Ansible errors.