cloudposse/atmos v1.210.1

on GitHub

what

• Streamlined configuration section with minimal-first approach (only workspace_id required)
• Moved advanced options like base_url and endpoint into an "Advanced" tab
• Reordered authentication methods to highlight GitHub OIDC as the recommended approach
• Clarified that Atmos Pro doesn't issue API keys or personal access tokens
• Emphasized that workspace_id is not a secret and safe to commit to version control

why

Atmos Pro is a commercial product and users should have the simplest possible path to get started. The configuration docs were showing empty fields with no guidance, which creates cluttered configs. This update leads with the essentials and moves advanced/uncommon patterns (like manual bearer token exchange) to a collapsible section.

references

Commercial product UX improvement — reducing configuration friction for new users.

Summary by CodeRabbit

• Documentation
  • Reorganized Pro configuration documentation with Minimal and Advanced configuration examples.
  • Enhanced authentication guidance with improved GitHub OIDC Token Exchange documentation.
  • Updated environment variable documentation and descriptions for clarity.

what

• Created new documentation page for version.use configuration explaining version pinning, supported formats (semver, latest, pr:, sha:), CLI flag override, and precedence hierarchy
• Updated the main version configuration overview to include version.use in the YAML example
• Added ATMOS_USE_VERSION and ATMOS_VERSION environment variables to the reference
• Updated configuration index description to clarify version settings cover pinning, checking, and constraint enforcement

why

The version.use feature was already implemented in code but missing from the configuration reference documentation. This documentation gap meant users couldn't find authoritative guidance on how to configure project-wide version pinning. The feature was announced in a blog post but lacked canonical reference docs alongside version.check and version.constraint.

references

• Blog post: Introducing the Atmos Version Manager
• How-to guide: Using Profiles for Atmos Version Management

Summary by CodeRabbit

• Documentation
  • Clarified Version configuration description to emphasize version pinning, automatic checks, and constraint enforcement.
  • Added a comprehensive guide for version pinning with usage examples (CLI, profiles, CI/CD) and precedence rules.
  • Expanded environment variable docs and controls for version selection, checking, caching, and enforcement.

what

• Fix failed to find import error when ATMOS_BASE_PATH env var (or --base-path flag / atmos_base_path provider parameter) is set to a relative path like .terraform/modules/monorepo
• Fix failed to find import error in atmos describe affected caused by git root discovery interfering with configured base_path
• Improve failed to find import error messages with actionable hints and context (pattern, stacks base path)
• Formalize base path resolution semantics with 4-category classification and source-dependent anchoring

why

Since v1.202.0, resolveAbsolutePath() routes simple relative paths through git root discovery. This breaks two scenarios:

Scenario 1: terraform-provider-utils with ATMOS_BASE_PATH env var

When a user sets ATMOS_BASE_PATH=.terraform/modules/monorepo on a CI/CD worker (e.g., Spacelift), the path should resolve relative to CWD (/project/components/terraform/iam-delegated-roles/.terraform/modules/monorepo). Instead, git root discovery resolves it to /project/.terraform/modules/monorepo — a path that doesn't exist — causing failed to find import.

Scenario 2: atmos describe affected

In CI environments where the working directory structure differs from expectations, git root discovery can compute the stacks base path incorrectly, causing stack processing to fail with failed to find import.

Error message problem

The bare failed to find import error provides no context about which import failed or what path was searched, making it impossible for users to diagnose.

Fix approach

Fix 1: Source-aware base path resolution

Every base_path value is classified into one of four categories:

A BasePathSource field on AtmosConfiguration tracks whether the base path came from a runtime source or config file:

• Runtime sources (env var ATMOS_BASE_PATH, CLI flag --base-path, provider param atmos_base_path): set BasePathSource = "runtime". Dot-prefixed paths resolve relative to CWD (shell convention).
• Config source (base_path in atmos.yaml): dot-prefixed paths resolve relative to the directory containing atmos.yaml (config-file convention).
• Bare paths are source-independent — they always go through git root search regardless of where they were specified.

resolveAbsolutePath() now accepts a source parameter and routes dot-prefixed paths through resolveDotPrefixPath(). The tryResolveWithGitRoot() function adds os.Stat validation — if the git-root-joined path doesn't exist but the CWD-relative path does, it falls back to the CWD-relative path.

Fix 2: Actionable error messages

Wrap ErrFailedToFindImport with the error builder pattern in FindAllStackConfigsInPathsForStack, FindAllStackConfigsInPaths, and GetGlobMatches, adding hints about checking base_path, stacks.base_path, and ATMOS_BASE_PATH. All path resolution errors use errUtils.Build(errUtils.ErrPathResolution) for consistent errors.Is() classification.

Spacelift/provider scenario

ATMOS_BASE_PATH=./.terraform/modules/monorepo (recommended dot-slash form): classified as Dot, runtime source → resolves relative to CWD. Works correctly.

ATMOS_BASE_PATH=.terraform/modules/monorepo (existing bare form): classified as Bare, goes through git root search → os.Stat at git root fails → falls back to CWD. Also works correctly.

Git root discovery compatibility

The "run Atmos from any subdirectory" feature (v1.202.0+) is not affected:

• Source-aware resolution only changes behavior for dot-prefixed paths from runtime sources
• Bare paths ("stacks", "foo/bar") go through the same git root search regardless of source
• Empty base_path returns git root (unchanged)
• Config-file dot-prefixed paths (base_path: "." in atmos.yaml) continue to resolve relative to the config directory

Verified by existing integration tests: describe_component_from_nested_dir, terraform_plan_from_nested_dir, terraform_plan_with_current_directory.

Backward compatibility

• Dot-prefixed paths from runtime sources (ATMOS_BASE_PATH=".", --base-path=./foo): now resolve relative to CWD (shell convention). Previously resolved relative to config dir. This matches user expectations — in a shell, . means "here" (CWD)
• Dot-prefixed paths from config file (base_path: "." in atmos.yaml): continue to resolve relative to atmos.yaml location — no change
• Bare paths ("stacks", ".terraform/modules/monorepo"): go through git root search regardless of source, with os.Stat fallback to CWD — source-independent
• Default/empty base_path: continues to use git root discovery (the v1.202.0 behavior)
• ATMOS_GIT_ROOT_BASEPATH=false: continues to work as a full opt-out of git root discovery

references

• closes #2183
• PRD: docs/prd/base-path-resolution-semantics.md
• Fix doc: docs/fixes/2026-03-17-failed-to-find-import-base-path-resolution.md
• Related: terraform-provider-utils v1.32.0+ with ATMOS_BASE_PATH env var

Summary

• Updated "What You Get" section with all implemented CI features (summaries, status checks, output variables, planfile storage, custom templates, auto-detection)
• Added atmos.yaml CI configuration tab to Quick Start section with full CI config and planfile storage examples
• Updated "Example Output" to render as live markdown matching actual GitHub Actions summary style (badges, diff blocks, collapsible sections, terraform outputs)
• Updated "Learn More" with links to all CI documentation pages
• Marked PR comments as "coming soon" and removed drift detection per feedback

Test plan

• Verify blog post renders correctly on Docusaurus site
• Verify all internal links resolve (/cli/configuration/ci, /ci, /ci/planfile-storage)
• Verify shields.io badges render as images
• Verify collapsible details sections work
• Verify tabs (GitHub Actions / profiles / atmos.yaml) render correctly

Summary by CodeRabbit

• Documentation
  • Enhanced documentation with improved formatting and richer examples for CI integration scenarios.
  • Added detailed configuration examples and expanded output samples with enhanced structure and clarity.