What Changed​

Atmos now includes a new !aws.organization_id YAML function that retrieves the AWS Organization ID by calling the AWS Organizations DescribeOrganization API. This complements the existing AWS context functions: !aws.account_id, !aws.caller_identity_arn, !aws.caller_identity_user_id, and !aws.region.

components:
  terraform:
    my-component:
      vars:
        organization_id: !aws.organization_id

Why This Matters​

The AWS Organization ID is commonly needed for:

• Service Control Policies (SCPs) - Scoping policies to the organization
• Cross-account trust policies - Referencing the organization in IAM conditions
• Resource tagging - Tagging resources with the organization ID for cost allocation
• Multi-account governance - Configuring components that operate at the organization level

Previously, users had to hardcode the organization ID or use workarounds. Now it's available dynamically, just like other AWS context values.

How to Use It​

Use !aws.organization_id anywhere in your stack YAML files:

components:
  terraform:
    governance:
      vars:
        org_id: !aws.organization_id
        tags:
          OrganizationId: !aws.organization_id

The function requires the organizations:DescribeOrganization IAM permission and the account must be a member of an AWS Organization.

Results are cached for the duration of the CLI invocation, so multiple references only make one API call.

This is equivalent to Terragrunt's get_aws_org_id() function.

Get Involved​

• Read the documentation for full details
• Report issues on GitHub

What Changed​

Stores (!store YAML function) can now reference an Atmos auth identity via a new identity field in the store configuration. When set, the store uses that identity's credentials instead of the default credential chain (environment variables, default AWS profiles, etc.).

stores:
  prod/aws-ssm:
    type: aws-ssm-parameter-store
    identity: prod-admin
    options:
      region: us-east-1

This works with all cloud-backed store types:

• AWS SSM Parameter Store - loads AWS config from realm-scoped credential and config files
• Azure Key Vault - authenticates via DefaultAzureCredential with tenant hint from auth context
• Google Secret Manager - uses realm-scoped application default credentials file

Redis and Artifactory stores do not support identity-based authentication since they don't map to cloud provider identity types.

Realm Compatibility​

Store identities are fully compatible with Atmos auth realms. When a realm is configured, the auth system embeds the realm into credential file paths (e.g., ~/.config/atmos/{realm}/aws/{provider}/credentials). These realm-scoped paths flow through the resolver to stores automatically -- store code never needs to know about realms.

This means stores in different realms use isolated credentials, preventing cross-environment credential collisions.

Why This Matters​

Previously, stores always used the default credential chain, which meant separate credential management for secrets access vs. Terraform execution. Now you can use the same identity system for both, simplifying credential management and enabling more granular access control.

How to Use It​

1. Configure an identity in your atmos.yaml auth section (as you normally would for atmos auth).
2. Add the identity field to your store configuration referencing that identity name.
3. The store will automatically authenticate using that identity on first access.

stores:
  prod/aws-ssm:
    type: aws-ssm-parameter-store
    identity: prod-admin
    options:
      region: us-east-1

  staging/azure-kv:
    type: azure-key-vault
    identity: staging-azure
    options:
      vault_url: https://staging-vault.vault.azure.net

  prod/gsm:
    type: google-secret-manager
    identity: gcp-prod
    options:
      project_id: my-gcp-project

Stores without the identity field continue to work exactly as before -- this is a fully backward-compatible change.

Get Involved​

Have questions or feedback? Open an issue on GitHub.

What's New​

The --use-version flag now accepts PR numbers and commit SHAs, making it trivial to test features from any open pull request or specific commit:

# Test a feature from PR #2040
atmos --use-version pr:2040 terraform plan

# Numbers are auto-detected as PRs
atmos --use-version 2040 describe stacks

# Test a specific commit by SHA
atmos --use-version sha:ceb7526 version

# SHAs are auto-detected (7-40 hex chars)
atmos --use-version ceb7526be terraform plan

How It Works​

When you specify a PR number or SHA, Atmos:

1. Fetches the artifact - Downloads the correct platform binary (Linux, macOS, Windows) from GitHub Actions
2. Caches locally - Stores the binary in ~/.local/share/atmos/toolchain/bin/ with metadata for fast subsequent runs
3. Re-executes - Runs your command using the specified version of Atmos

For PR versions, the cache uses a 1-minute TTL before checking for new commits, so repeated runs within that window are instant.

For SHA versions, the cache is permanent since commits are immutable - once installed, a SHA version is always ready to use.

Clear Error Messages​

When things go wrong, you get actionable guidance:

• Invalid version format: Clear message showing valid formats (PR number, pr:NNNN, sha:XXXXXXX, or semver)
• Missing GitHub token: Instructions for authenticating via gh CLI or environment variable
• PR/commit not found: Direct link to the PR or commit page
• CI workflow failing: Explanation of why artifacts might be missing
• Unsupported platform: Suggests alternatives

Requirements​

PR artifact installation requires GitHub authentication. The feature checks for tokens in this order:

1. ATMOS_GITHUB_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. GitHub CLI (gh) authentication

Getting Started​

# Authenticate with GitHub CLI (if not already)
gh auth login

# Test a PR
atmos --use-version pr:2040 version

# Test a specific commit
atmos --use-version sha:ceb7526 version

This feature complements our existing PR feature releases infrastructure, making it even easier to validate changes before they merge.

What Changed​

Atmos now correctly generates backend.tf.json configuration for Terraform Cloud and Terraform Enterprise backends when using the !terraform.output YAML function. This was previously broken because Terraform Cloud requires a different backend structure than other backend types.

Why This Matters​

The !terraform.output YAML function is powerful—it lets you reference outputs from one component in another component's configuration, creating declarative dependencies between infrastructure components. However, this feature was silently failing for teams using Terraform Cloud or Terraform Enterprise backends.

When Atmos needed to fetch outputs from a dependency component, it would generate an incorrect backend configuration that Terraform would reject:

Error: Unsupported backend type on backend.tf.json line 4, in terraform.backend: 4:
"cloud": { There is no explicit backend type named "cloud". To configure HCP
Terraform, declare a 'cloud' block instead.

This forced teams to either:

• Avoid using !terraform.output with Terraform Cloud
• Switch to S3/Azure/GCS backends just to use this feature
• Manually work around the limitation with terraform_remote_state data sources

The Problem​

Terraform Cloud has a unique backend configuration structure. Unlike other backends (S3, Azure, GCS) that nest under terraform.backend.<type>, Terraform Cloud's configuration must be placed directly under terraform.cloud:

Incorrect (what Atmos was generating):

{
  "terraform": {
    "backend": {
      "cloud": {
        "organization": "my-org",
        "workspaces": {
          "name": "my-workspace"
        }
      }
    }
  }
}

Correct (what Terraform Cloud expects):

{
  "terraform": {
    "cloud": {
      "organization": "my-org",
      "workspaces": {
        "name": "my-workspace"
      }
    }
  }
}

This subtle difference caused Terraform to fail during initialization, preventing the !terraform.output function from fetching outputs.

How It Works​

Atmos now detects when a component uses a Terraform Cloud backend and generates the correct JSON structure automatically. The fix is applied in the generateBackendConfig function within the pkg/terraform/output package.

When you use !terraform.output to reference another component's outputs, Atmos:

1. Determines the backend type of the dependency component
2. Generates the appropriate backend.tf.json structure
3. For Terraform Cloud/Enterprise backends specifically, places the configuration under terraform.cloud instead of terraform.backend.cloud
4. Runs terraform init and terraform output to fetch the values
5. Returns the output values for use in your stack configuration

Example Usage​

Define your EKS cluster component with a Terraform Cloud backend:

# stacks/eks-cluster.yaml
components:
  terraform:
    cluster:
      backend_type: cloud
      backend:
        cloud:
          organization: "my-org"
          workspaces:
            name: "eks-cluster-prod"
      vars:
        cluster_version: "1.29"
        # ... other cluster configuration

Now reference the cluster outputs in your application component:

# stacks/my-app.yaml
components:
  terraform:
    my-app:
      backend_type: cloud
      backend:
        cloud:
          organization: "my-org"
          workspaces:
            name: "my-app-prod"
      vars:
        # Reference cluster outputs using !terraform.output
        cluster_endpoint: !terraform.output cluster.cluster_endpoint
        cluster_ca_cert: !terraform.output cluster.cluster_certificate_authority_data
        cluster_name: !terraform.output cluster.cluster_name

When Atmos processes my-app, it will:

• Detect that cluster uses a Terraform Cloud backend
• Generate the correct backend configuration
• Fetch the outputs from the eks-cluster-prod workspace
• Make them available to your my-app component

What's Next​

This fix ensures feature parity across all backend types. Whether you're using S3, Azure Blob Storage, GCS, or Terraform Cloud, the !terraform.output function now works consistently.

For teams already using Terraform Cloud, this unlocks the full power of declarative component dependencies without manual workarounds.

Get Involved​

Try out the enhanced !terraform.output function with Terraform Cloud and let us know what you think! File issues or feature requests on GitHub.

The Problem​

Previously, atmos describe affected only detected components that were modified between two Git commits. It worked by iterating over stacks in HEAD (current branch) and comparing them to BASE (target branch). This meant:

• Components removed from a stack were invisible to the affected detection
• Entire stacks that were deleted went unnoticed
• CI/CD pipelines had no automated way to know which resources needed terraform destroy
• Users had to manually identify and destroy removed components, risking resource leaks

The Solution​

The describe affected command now performs a second pass that iterates over BASE stacks to detect deletions:

1. Deleted components: Components that exist in BASE but not in HEAD (within the same stack)
2. Deleted stacks: Entire stacks that exist in BASE but not in HEAD

Deleted components are marked with new fields in the output:

{
  "component": "monitoring",
  "component_type": "terraform",
  "stack": "prod-us-east-1",
  "affected": "deleted",
  "deleted": true,
  "deletion_type": "component"
}

New Output Fields​

New Affected Reasons​

Filtering Deleted vs Modified Components​

Use the --query flag or jq to separate deleted components from modified ones:

# Get only deleted components (for destruction)
atmos describe affected --query '[.[] | select(.deleted == true)]'

# Get only modified components (for apply)
atmos describe affected --query '[.[] | select(.deleted != true)]'

Using with List Affected​

The atmos list affected command also supports deleted detection, providing a human-readable table view:

# List all affected components including deleted ones
atmos list affected

# Filter deleted components in JSON format
atmos list affected --format json | jq '[.[] | select(.deleted == true)]'

# Custom columns showing deletion status
atmos list affected --columns "Component={{ .component }},Stack={{ .stack }},Deleted={{ .deleted }}"

The deleted and deletion_type fields are available for custom column templates.

CI/CD Integration Example​

Here's how to separate apply and destroy workflows in GitHub Actions:

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      modified: ${{ steps.affected.outputs.modified }}
      deleted: ${{ steps.affected.outputs.deleted }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: cloudposse/github-action-setup-atmos@v2

      - name: Detect affected
        id: affected
        run: |
          atmos describe affected --format json > affected.json

          # Separate modified and deleted components
          jq '[.[] | select(.deleted != true)]' affected.json > modified.json
          jq '[.[] | select(.deleted == true)]' affected.json > deleted.json

          echo "modified=$(cat modified.json | jq -c)" >> $GITHUB_OUTPUT
          echo "deleted=$(cat deleted.json | jq -c)" >> $GITHUB_OUTPUT

  apply:
    needs: detect-changes
    if: needs.detect-changes.outputs.modified != '[]'
    strategy:
      matrix:
        include: ${{ fromJson(needs.detect-changes.outputs.modified) }}
    steps:
      - uses: actions/checkout@v4
      - uses: cloudposse/github-action-setup-atmos@v2
      - run: atmos terraform apply ${{ matrix.component }} -s ${{ matrix.stack }}

  destroy:
    needs: detect-changes
    if: needs.detect-changes.outputs.deleted != '[]'
    environment: production  # Requires manual approval
    strategy:
      matrix:
        include: ${{ fromJson(needs.detect-changes.outputs.deleted) }}
    steps:
      # Check out BASE branch - deleted component config only exists there
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.base_ref }}
      - uses: cloudposse/github-action-setup-atmos@v2
      - run: atmos terraform destroy ${{ matrix.component }} -s ${{ matrix.stack }} --auto-approve

Edge Cases​

• Abstract components (metadata.type: abstract) are not reported as deleted since they are blueprints and not provisioned
• Component renames appear as both a deletion (old name) and a new component (new name)

Related Documentation​

• Describe Affected Command - Full command reference
• List Affected Command - Human-readable table view
• Affected Stacks GitHub Action - CI/CD integration
• Component Inheritance - Abstract component patterns

What Changed​

When using !terraform.state to read Terraform or OpenTofu state directly from S3, Atmos now supports SSE-C (Server-Side Encryption with Customer-Provided Keys). Previously, state files stored in SSE-C encrypted buckets were inaccessible through !terraform.state, requiring workarounds to retrieve outputs.

You can provide the SSE-C key in two ways:

1. Backend attribute in your stack configuration:

   components:
     terraform:
       my-component:
         backend:
           s3:
             sse_customer_key: "your-base64-encoded-key"
   

2. Environment variable:

   export AWS_SSE_CUSTOMER_KEY="your-base64-encoded-key"
   

The backend attribute takes precedence over the environment variable, following the same convention as OpenTofu and Terraform.

This also works with remote_state_backend overrides, so you can configure SSE-C keys per-component when referencing remote state.

Why This Matters​

Organizations that use SSE-C for S3 state encryption previously couldn't use !terraform.state to reference outputs from those state files. This meant either switching encryption strategies or falling back to !terraform.output (which runs terraform output and requires the full Terraform/OpenTofu binary). With SSE-C support, !terraform.state reads the state file directly from S3 with the correct encryption headers, keeping lookups fast and dependency-free.

Note that this only affects !terraform.state (which reads state files directly from S3). The !terraform.output function is unaffected since it delegates to Terraform/OpenTofu, which already handles SSE-C natively.

Get Involved​

Have questions or feedback? Join us on Slack or open an issue on GitHub.

What Changed​

• Added GCP providers: gcp/adc and gcp/workload-identity-federation.
• Added GCP identities: gcp/service-account and gcp/project.
• Implemented provider-scoped file isolation at ~/.config/atmos/gcp/<provider-name>/....
• Integrated GCP auth with atmos auth login, atmos auth whoami, and Terraform execution.

Why This Matters​

• Use the same auth flow across AWS, Azure, and GCP.
• Avoid long-lived keys in CI/CD with Workload Identity Federation.
• Keep credentials isolated per provider and identity, without touching user gcloud config.

How to Use It​

For local development with ADC:

auth:
  providers:
    gcp-adc:
      kind: gcp/adc
      project_id: my-project

  identities:
    terraform:
      kind: gcp/service-account
      default: true
      via:
        provider: gcp-adc
      principal:
        service_account_email: terraform@my-project.iam.gserviceaccount.com

For GitHub Actions with Workload Identity Federation — no token_source needed, everything is auto-detected:

auth:
  providers:
    gcp-wif:
      kind: gcp/workload-identity-federation
      project_number: "123456789012"
      workload_identity_pool_id: github-pool
      workload_identity_provider_id: github-provider
      service_account_email: ci-sa@my-project.iam.gserviceaccount.com

In GitHub Actions, Atmos automatically detects ACTIONS_ID_TOKEN_REQUEST_URL, constructs the correct WIF audience, and fetches the OIDC token — no manual token_source, url, or audience configuration required. Just ensure your workflow has id-token: write permission.

Authenticate and verify:

atmos auth login --identity terraform
atmos auth whoami

Get Involved​

Feedback and testing reports are welcome. If you use GCP in CI/CD, try the WIF provider and share any edge cases you encounter.

The Problem​

When working with multiple repositories that use the same identity names (like core-root/terraform), credentials from one repository could leak into another. This was especially problematic for consultants and engineers managing infrastructure across multiple customer environments.

What Changed​

Credentials are now stored in realm-scoped paths and keyring keys:

# Before
~/.config/atmos/aws/{provider}/credentials
Keyring: {identity}

# After
~/.config/atmos/{realm}/aws/{provider}/credentials
Keyring: atmos:{realm}:{identity}

The realm is computed automatically based on your project location, ensuring each repository has isolated credentials.

Realm Computation​

Realms are determined by priority:

1. Environment variable: ATMOS_AUTH_REALM - explicit override
2. Config file: auth.realm in atmos.yaml - per-project setting
3. Auto-generated: SHA256 hash of the atmos.yaml path (first 8 characters)

Viewing Your Realm​

The atmos auth whoami and atmos auth login commands now display the active realm:

atmos auth login --identity my-identity

Realm     a1b2c3d4 (auto)
Provider  aws-sso
Identity  my-identity
Region    us-east-1

New Logout Options​

A new --all-realms flag allows logging out from all realms across all repositories:

# Logout from current realm only
atmos auth logout --all

# Logout from ALL realms (all repositories)
atmos auth logout --all --all-realms

Breaking Change​

This is a breaking change. Existing credentials will not be found after updating because they were stored in the old path format.

Action required: Run atmos auth login after updating to re-authenticate.

Get Involved​

Found an issue or have a feature request? Open an issue on GitHub.

What Changed​

You can now define environment variables in workflow YAML files at two levels:

• Workflow-level: Applied to all steps in the workflow
• Step-level: Applied to a specific step, overriding workflow-level variables with the same key

Environment variables are merged hierarchically, with step-level values taking precedence over workflow-level values for the same keys.

Example​

workflows:
  deploy:
    description: Deploy with custom environment
    env:
      FOO: bar
      BAZ: workflow-value
    steps:
      - command: echo "$FOO - $BAZ"
        type: shell
        env:
          BAZ: step-value

Running this workflow outputs bar - step-value because:

• FOO is inherited from the workflow level (bar)
• BAZ is overridden by the step level (step-value)

Why This Matters​

This feature enables several use cases:

• Consistent environment setup: Define common variables once at the workflow level
• Step-specific overrides: Override variables for specific steps without duplicating configuration
• Integration with external tools: Pass environment variables to shell commands and Terraform

Environment Variable Precedence​

The full precedence order (lowest to highest priority):

1. System environment variables
2. Global env from atmos.yaml
3. Workflow-level env
4. Step-level env
5. Auth identity env vars (if identity is specified)

Get Involved​

Have questions or feedback? Join us on Slack or open an issue on GitHub.

What Changed​

Ansible joins Terraform, Helmfile, and Packer as a native component type in Atmos:

• New atmos ansible playbook command executes Ansible playbooks with stack-based configuration
• New atmos ansible version command displays Ansible version information
• Full-stack processor support including inheritance, vars, env, settings, and auth sections
• Automatic variable file generation passed to Ansible via --extra-vars @<varfile>
• Native flag passthrough via -- separator for any Ansible option

Why This Matters​

Infrastructure automation typically involves two layers: provisioning (creating resources) and configuration (setting up software). Teams often use Terraform for the first and Ansible for the second, but manage them with separate tooling and workflows.

With Ansible component support, you can:

• Manage both layers from one tool with consistent patterns
• Share variables between Terraform and Ansible components in the same stack
• Apply the same inheritance model to Ansible playbooks
• Use familiar Atmos workflows for configuration management

How to Use It​

Configuration​

Add Ansible configuration to atmos.yaml:

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

Stack Manifest​

Define Ansible components alongside Terraform:

components:
  terraform:
    vpc:
      vars:
        cidr_block: "10.0.0.0/16"

  ansible:
    webserver:
      vars:
        app_name: myapp
        app_port: 8080
      settings:
        ansible:
          playbook: site.yml
          inventory: inventory/production

Commands​

# Show Ansible version
atmos ansible version

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

# Override playbook and inventory
atmos ansible playbook webserver -s prod -p deploy.yml -i hosts.ini

# Pass native Ansible flags
atmos ansible playbook webserver -s prod -- --check --verbose

# Use aliases
atmos an pb webserver -s prod

Get Involved​

• Report issues or request features on GitHub
• Join the discussion in Slack

What Changed​

Artifactory Store Fix​

When using Artifactory as a store backend with nested directory structures, retrieving values would fail with a "file not found" error even though the data existed. This happened because files were being downloaded to unexpected locations within temporary directories.

For example, storing a value at dev/myapp/private_ip and then trying to retrieve it would fail because Atmos was looking for the file in the wrong place.

This is now fixed. Retrieving values from Artifactory works correctly regardless of how deeply nested your paths are.

Documentation Corrections​

The store documentation had several issues that could cause confusion:

• Wrong field names: Examples showed backend and config instead of the correct type and options
• Wrong store type names: Examples showed aws/ssm instead of the correct aws-ssm-parameter-store
• Non-existent backends: Vault and AWS Secrets Manager were documented but aren't actually implemented
• Missing backends: Azure Key Vault and Google Secret Manager were implemented but not documented
• Artifactory setup: Added guidance on using Generic repository type in JFrog Artifactory

Why This Matters​

If you've been struggling to get Artifactory working as a store backend, especially with nested paths, this fix should resolve those issues. And if you've been confused by store configuration examples that didn't work, the documentation now reflects the actual supported backends and correct configuration format.

Get Involved​

Have questions or feedback? Join us on Slack or open an issue on GitHub.

What Changed​

The workdir provisioning system has been enhanced with version tracking and intelligent re-provisioning:

• Version-aware re-provisioning - When a remote source version changes in your configuration, Atmos automatically re-provisions the workdir with the new version
• URI change detection - Changing the source URI triggers re-provisioning to ensure you always have the correct source
• Incremental local sync - Local component changes are synced using per-file checksums, copying only modified files
• TTL-based cleanup - Stale workdirs can be cleaned up automatically based on last-accessed time
• Enhanced metadata - Workdirs now track source_uri, source_version, and last_accessed timestamps

Why This Matters​

Previously, if you updated a component's source version in your stack configuration, you had to manually clean the workdir before the change would take effect. Now Atmos handles this automatically:

• Seamless version upgrades - Change version: "0.24.0" to version: "0.25.0" and run terraform plan - Atmos detects the mismatch and re-provisions automatically
• Reduced disk usage - The --expired cleanup option removes workdirs that haven't been accessed within a configurable TTL
• Faster local iteration - Only modified files are synced to workdirs, making local development faster
• Full visibility - The workdir list and workdir show commands now display version and access information

How to Use It​

Version-Aware Provisioning​

Configure a component with a source version:

components:
  terraform:
    vpc:
      source:
        uri: "github.com/cloudposse/terraform-aws-vpc//src"
        version: "0.25.0"
      provision:
        workdir:
          enabled: true

When you change the version, Atmos automatically re-provisions:

$ atmos terraform plan vpc -s dev
# Output: "Source version changed (0.24.0 → 0.25.0)"
# Workdir is re-provisioned with the new version

TTL-Based Cleanup​

Clean workdirs that haven't been accessed in a week:

$ atmos terraform workdir clean --expired --ttl=7d
Cleaning expired workdirs (TTL: 7d)...
  ✓ Removed dev-nginx (last accessed 14 days ago)
  ✓ Removed staging-api (last accessed 10 days ago)
Cleaned 2 expired workdirs

Preview what would be cleaned with dry-run:

$ atmos terraform workdir clean --expired --ttl=7d --dry-run
Dry run: would clean 2 expired workdir(s) (TTL: 7d):
  - dev-nginx (last accessed 14d 2h)
  - staging-api (last accessed 10d 5h)

Enhanced Workdir Information​

View detailed workdir information:

$ atmos terraform workdir show vpc --stack dev
✓ Workdir Status

  Name            dev-vpc
  Component       vpc
  Stack           dev
  Source Type     remote
  Source URI      github.com/cloudposse/terraform-aws-vpc//src
  Source Version  0.25.0
  Path            .workdir/terraform/dev-vpc
  Created         2026-01-20 10:00:00 UTC
  Updated         2026-01-22 14:30:00 UTC
  Last Accessed   2026-01-22 14:30:00 UTC

List workdirs with version and access information:

$ atmos terraform workdir list
COMPONENT   STACK   TYPE     VERSION   LAST_ACCESSED        PATH
vpc         dev     remote   0.25.0    2026-01-22 14:30     .workdir/terraform/dev-vpc
my-local    dev     local    -         2026-01-22 10:15     .workdir/terraform/dev-my-local

TTL Format​

The --ttl flag supports various duration formats:

• Time units: 30m, 2h, 7d (minutes, hours, days)
• Keywords: hourly, daily, weekly, monthly
• Seconds: 3600 (plain integers are interpreted as seconds)

Get Involved​

Have feedback on the version-aware provisioning feature? Open an issue on GitHub or join the discussion in our Slack community.

The Problem​

When using atmos describe affected to identify components impacted by code changes, the command was only detecting stack configuration changes but missing actual component file changes. For example, modifying a main.tf file inside a Terraform component folder would not mark that component as affected.

This issue occurred because git diff returns file paths relative to the git repository root, while the path resolution was using the current working directory. This caused path mismatches in the following scenarios:

• Using -C flag: Running atmos -C path/to/project describe affected from a parent directory
• Subdirectory projects: When atmos.yaml is located in a subdirectory of the git repository
• Monorepo setups: When multiple Atmos projects share a single git repository

The Fix​

We updated the changed files indexing logic to properly resolve relative paths against the git repository root instead of the current working directory. The fix ensures that:

• Relative paths from git diff are correctly resolved against the git repo root
• Component folder changes are detected regardless of where Atmos is executed from
• Individual file changes within component directories are properly tracked

Example​

Now when you modify component files, atmos describe affected correctly identifies them:

# Modify a component file
echo "# comment" >> components/terraform/vpc/main.tf

# Run describe affected
atmos describe affected --ref refs/heads/main

# Output now includes the vpc component
[
  {
    "component": "vpc",
    "stack": "plat-ue2-dev",
    "affected": "component"
  }
]

Usage​

Upgrade to the latest version of Atmos and run:

atmos describe affected --ref refs/heads/main

The command now correctly detects:

• Changes to component folders (Terraform, Helmfile, Packer)
• Changes to individual files within components
• Stack configuration changes (as before)
• Vendored components configured with source (even without an explicit component field)

This fix ensures your CI/CD pipelines accurately identify which components need to be deployed based on actual code changes.

The Problem​

When using Atmos vendoring with the source attribute to pull components from remote repositories, the atmos describe affected command was not detecting changes to those component files. This occurred because the affected detection logic required an explicit component field to determine which folder to monitor for changes.

Components configured like this were not being tracked:

components:
  terraform:
    vpc-remote:
      source:
        uri: "github.com/cloudposse/terraform-aws-vpc//."
        version: "4.0.0"
      vars:
        enabled: true

The Fix​

The affected detection now defaults to using the component name (the YAML key, e.g., vpc-remote) as the component folder path when no explicit component field is specified. This ensures that:

• Components using source for vendoring are properly tracked
• Components without explicit component field inheritance are detected
• All component types (Terraform, Helmfile, Packer) benefit from this fix

What About Workdir?​

If you use provision.workdir with your vendored components, the detection still works correctly. The describe affected command tracks changes in the source files (components/terraform/<component>/), not the runtime workdir (.workdir/). Since .workdir/ is in .gitignore and created at runtime, it doesn't affect change detection.

Example​

Now when you modify vendored component files, atmos describe affected correctly identifies them:

# Stack configuration with source vendoring
components:
  terraform:
    vpc-production:
      source:
        uri: "github.com/cloudposse/terraform-aws-vpc//."
        version: "4.0.0"
        included_paths:
          - "**/*.tf"
      vars:
        environment: "production"

After running atmos vendor pull and making changes:

# Modify a vendored component file
echo "# update" >> components/terraform/vpc-production/main.tf

# Run describe affected
atmos describe affected --ref refs/heads/main

# Output now includes the vpc-production component
[
  {
    "component": "vpc-production",
    "stack": "prod-us-east-1",
    "affected": "component"
  }
]

Related Documentation​

• Vendoring Overview - Learn about Atmos vendoring capabilities
• Source Configuration - Configure source URIs and protocols
• Just-in-Time Vendoring - Inline source declarations
• Vendor Pull Command - Download vendored components

The Feature​

Locals can now use all Atmos YAML functions to fetch dynamic values:

• !env - Environment variables
• !exec - Command execution
• !store - Store lookups
• !terraform.state - Terraform state queries
• !terraform.output - Terraform outputs from other components

Example with Environment Variables​

locals:
  api_endpoint: !env API_ENDPOINT
  api_url: "https://{{ .locals.api_endpoint }}/api/v1"

components:
  terraform:
    myapp:
      vars:
        api_url: "{{ .locals.api_url }}"

Example with Terraform State​

locals:
  # Fetch from another component's terraform state
  vpc_id: !terraform.state vpc .vpc_id
  subnet_ids: !terraform.state vpc .private_subnet_ids

components:
  terraform:
    eks:
      vars:
        vpc_id: "{{ .locals.vpc_id }}"
        subnet_ids: "{{ .locals.subnet_ids }}"

Example with Store​

locals:
  db_password: !store secrets/database .password
  connection_string: "postgresql://app:{{ .locals.db_password }}@db.example.com/mydb"

components:
  terraform:
    backend:
      vars:
        database_url: "{{ .locals.connection_string }}"

How It Works​

1. YAML functions in locals are processed during stack configuration loading
2. The resolved values are available to other locals and component vars
3. Locals can combine YAML function results with Go templates

Use Cases​

• Environment-specific configuration: Use !env to inject environment-specific values
• Cross-component references: Use !terraform.state to reference outputs from other components
• Secret management: Use !store to fetch secrets from your configured store
• Dynamic values: Use !exec to run commands and capture output

Upgrade​

Upgrade Atmos to get this feature. Existing locals configurations continue to work unchanged.

References​

• Locals Documentation
• YAML Functions Documentation

The Enhancement​

Previously, locals could only reference other locals via {{ .locals.* }}. Now they can also access:

• {{ .settings.* }} - Settings defined in the same file
• {{ .vars.* }} - Vars defined in the same file
• {{ .env.* }} - Environment variables

Example​

settings:
  version: v1

vars:
  stage: dev

locals:
  namespace: acme
  label: "{{ .locals.namespace }}-{{ .vars.stage }}-{{ .settings.version }}"

components:
  terraform:
    myapp:
      vars:
        name: "{{ .locals.label }}"

File-Scoped Context​

The context available to locals comes from the same file only. Locals cannot access settings or vars from imported files.

If you need values from imported files, use vars or settings (which inherit across imports).

Upgrade​

Upgrade Atmos to get this enhancement. Existing locals configurations will continue to work.

References​

• Locals Documentation
• DRY Configuration with Locals

What Changed​

Two new commands are available with flexible filtering:

# List all terraform sources across all stacks
atmos terraform source list

# List terraform sources in a specific stack
atmos terraform source list --stack dev

# List sources for a specific component across all stacks
atmos terraform source list vpc

# List sources for a specific component in a specific stack
atmos terraform source list vpc --stack dev

# Unified view: list sources across all component types
atmos list sources
atmos list sources --stack dev
atmos list sources vpc

Dynamic Output Columns​

The output adapts to your query:

Listing all stacks - Shows Stack column:

STACK        COMPONENT    URI                                                           VERSION
plat-dev     vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0
plat-prod    vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

Filtering by --stack - Omits Stack column since it's redundant:

COMPONENT    URI                                                           VERSION
eks          github.com/cloudposse/terraform-aws-components//modules/eks   1.450.0
rds          github.com/cloudposse/terraform-aws-components//modules/rds   1.449.0
vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

With derived components - Shows Folder column when component names differ from their base component:

COMPONENT        FOLDER    URI                                                           VERSION
vpc/production   vpc       github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0
vpc/staging      vpc       github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

The Folder column only appears when there's a difference to show, keeping output clean for simple cases.

Multi-Type Listing​

The atmos list sources command includes a Type column since it lists sources across all component types (terraform, helmfile, packer) in a unified view:

STACK        TYPE        COMPONENT    URI                                                           VERSION
plat-dev     helmfile    nginx        github.com/cloudposse/helmfile-components//charts/nginx       1.0.0
plat-dev     terraform   vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0
plat-prod    terraform   vpc          github.com/cloudposse/terraform-aws-components//modules/vpc   1.450.0

Why This Matters​

With the source provisioner, components can declare their source inline in stack configuration for just-in-time vendoring. The source list command helps you:

• Audit which components have source configured across your infrastructure
• Compare versions across stacks (same component, different versions)
• Debug source configuration issues
• Discover vendorable components in unfamiliar stacks

Output Formats​

Multiple output formats are supported for integration with other tools:

# Table (default, human-readable)
atmos list sources --format table

# JSON (for scripting)
atmos list sources --format json

# YAML (for configuration)
atmos list sources --format yaml

# CSV (for spreadsheets)
atmos list sources --format csv

# TSV (for tab-separated pipelines)
atmos list sources --format tsv

Documentation​

• Source Provisioner - JIT vendoring overview
• atmos list sources - Unified view across all component types
• atmos terraform source list - List Terraform sources
• atmos helmfile source list - List Helmfile sources
• atmos packer source list - List Packer sources

What Changed​

The atmos toolchain env command now supports a github format that outputs paths compatible with GitHub Actions' $GITHUB_PATH environment file. When running in GitHub Actions, it automatically detects and writes to $GITHUB_PATH.

New Features​

• --format github: Outputs one path per line, compatible with $GITHUB_PATH
• --output flag: Append output to any file instead of stdout
• Auto-detection: When $GITHUB_PATH is set, the github format automatically writes to it
• Improved error messages: Helpful hints guide you when tools aren't installed

How to Use It​

In your GitHub Actions workflow:

- name: Install Atmos toolchain
  run: |
    atmos toolchain install
    atmos toolchain env --format github

The next step in your workflow will have access to all your toolchain binaries (OpenTofu, Terraform, Helmfile, etc.) in the PATH.

Why This Matters​

Previously, integrating Atmos toolchain with GitHub Actions required shell tricks:

# Before: Manual PATH manipulation
- run: echo "$(atmos toolchain path)" >> $GITHUB_PATH

Now it's a single, intuitive command that handles everything automatically.

Get Involved​

Try out the new GitHub Actions integration and let us know what you think! File issues or feature requests on GitHub.

What Changed​

When using atmos terraform plan -s stack-name without specifying a component, the interactive "Choose a component" menu now correctly filters the component list:

• Abstract components (metadata.type: abstract) are hidden - they're templates, not deployable
• Disabled components (metadata.enabled: false) are hidden - they can't be deployed
• Stack-scoped filtering - only components in the specified stack appear

Why This Matters​

Previously, users would see all components from all stacks, including abstract base components that serve as templates. This was confusing and could lead to errors when selecting a component that couldn't actually be deployed.

Shell Completion Too​

Tab completion for component arguments also uses the same filtering logic, so you'll only see valid, deployable components when completing atmos terraform plan -s stack <TAB>.

What's New​

The new --format=github option for atmos terraform output automatically writes outputs to $GITHUB_OUTPUT in the format GitHub Actions expects, including proper handling of multiline values using heredoc syntax.

# In a GitHub Actions workflow
atmos terraform output vpc -s dev --format=github

This writes outputs directly to $GITHUB_OUTPUT, making them available to subsequent workflow steps.

Why This Matters​

Previously, passing Terraform outputs between GitHub Actions steps required manual formatting or shell scripting to handle:

• Multiline values (JSON objects, lists, multi-line strings)
• Special characters that need escaping
• The correct $GITHUB_OUTPUT file format

The github format handles all of this automatically:

• Single-line values are written as key=value
• Multiline values use heredoc syntax: key<<DELIMITER\nvalue\nDELIMITER
• Complex types (maps, arrays) are JSON-encoded for easy parsing

Example Workflow​

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Get Terraform Outputs
        id: outputs
        run: atmos terraform output vpc -s dev --format=github

      - name: Use Outputs
        run: |
          echo "VPC ID: ${{ steps.outputs.outputs.vpc_id }}"
          echo "Subnets: ${{ steps.outputs.outputs.private_subnet_ids }}"

Usage Options​

Automatic $GITHUB_OUTPUT Detection​

When running in GitHub Actions, the format automatically writes to $GITHUB_OUTPUT:

atmos terraform output vpc -s dev --format=github

Custom Output File​

You can specify a different output file if needed:

atmos terraform output vpc -s dev --format=github --output-file=outputs.txt

Combined with Other Options​

The github format works with other output options:

# Uppercase keys for conventional ENV_VAR naming
atmos terraform output vpc -s dev --format=github --uppercase

# Flatten nested maps
atmos terraform output vpc -s dev --format=github --flatten

# Skip init for faster execution in CI
atmos terraform output vpc -s dev --format=github --skip-init

Output Format Details​

Simple Values​

vpc_id=vpc-12345
region=us-east-1
enabled=true

Multiline Values (Heredoc)​

For values containing newlines, the format uses GitHub's heredoc syntax:

vpc_config<<ATMOS_EOF_vpc_config
{
  "id": "vpc-12345",
  "cidr": "10.0.0.0/16"
}
ATMOS_EOF_vpc_config

Documentation​

For complete documentation on terraform output formatting options, see:

• Terraform Output Command

Get Involved​

Try out the new GitHub Actions output format and let us know what you think! File issues or feature requests on GitHub.