github.com/cloudposse/atmos

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

• Adds a flags: block that sets defaults for terraform CLI execution flags — lock_timeout, lock, parallelism, refresh, compact_warnings — settable globally in atmos.yaml, at the stack level (root-level terraform: block), and per component, with field-level merge across all three layers.
• Atmos only injects a flag into subcommands that actually support it (e.g. terraform import gets only lock/lock_timeout; apply <planfile> never gets -refresh, since Terraform rejects it there; terraform test gets none).
• An explicit CLI-typed flag (e.g. atmos terraform plan vpc -s dev -- -lock-timeout=30s) always wins over any declared default.
• Adds ATMOS_COMPONENTS_TERRAFORM_FLAGS_* env var overrides for the global default, regenerates the atmos.yaml JSON schema, hand-extends the stack-config JSON schema, and documents the new block on the Terraform configuration page plus plan/apply/destroy/refresh/import command docs.
• Includes a changelog post and roadmap entry.

why

• Terraform/OpenTofu's own -lock-timeout default is 0s (fail immediately on state-lock contention), which caused avoidable failures whenever concurrent pipelines touched the same component's state around the same time. There was previously no declarative way to set a longer retry window — only a raw CLI pass-through flag that had to be retyped on every single invocation.
• Declaring a default once (fleet-wide, per stack, or per component) removes that repeated manual step and the class of flaky-looking pipeline failures it caused.

references

Summary by CodeRabbit

• New Features

  • Added declarative Terraform/OpenTofu CLI flag defaults for locking, timeouts, parallelism, refresh, and compact warnings.
  • Configure flags globally, per stack, or per component with layered precedence.
  • Added environment-variable support for Terraform flag overrides.
  • Explicit command-line flags take precedence over configured defaults.

• Bug Fixes

  • Invalid or misspelled Terraform flag names and values now produce clear errors.
  • Flag settings are preserved and merged across inheritance and overrides.

• Documentation

  • Added configuration guidance, environment-variable references, examples, and command-specific support details.

• Print a short status banner at startup whenever Atmos detects it's running inside a CI provider: the Atmos version/platform, whether Native CI mode (ci.enabled) is on or off, and whether Atmos Pro is configured.
• Detect legacy cloudposse/github-action-atmos-* marketplace actions (via GITHUB_ACTION_REPOSITORY) and emit a warning nudging migration to Native CI.
• New pkg/ci/startup package holds the decision logic (kept out of cmd//internal/exec per repo convention); pkg/ci/providers/github gained the legacy-action env-var check.

why

• Misconfiguration (forgetting ci.enabled: true, or running without a Pro workspace configured) was previously silent until something failed downstream — this surfaces it immediately in CI logs.
• Users still on the older marketplace actions have no signal that Native CI exists or that they should migrate.

references

• N/A

Summary by CodeRabbit

• New Features

  • Added automatic CI startup status messages showing the current Atmos version.
  • Displays whether Native CI and Atmos Pro capabilities are enabled.
  • Warns when running through a legacy GitHub Action integration and recommends migrating to Native CI.
  • Startup information appears automatically for applicable CI commands.
  • Status output remains hidden for help, completion, and non-CI commands.

• Documentation

  • Added documentation describing the CI startup status banner and migration guidance.

🚀 Enhancements

• Add a provides: field to custom-command arguments: and flags:, replacing the two inconsistent spellings of the same "this value provides the component/stack name" concept: type: component/type: stack on arguments, and semantic_type: component/semantic_type: stack on flags.
• Deprecate Type (on CommandArgument) and SemanticType (on CommandFlag) via the existing jsonschema_extras deprecation pattern (schema marks them deprecated with x-atmos-replacement: provides), with a new EffectiveProvides() helper so existing configs using the old fields keep working unchanged.
• Regenerate the committed JSON Schema and update docs (arguments.mdx, flags.mdx, component.mdx, custom.mdx), the examples/custom-components/ fixture, and the atmos-modernization skill's legacy-pattern checklist.

why

• semantic_type existed only on CommandFlag because Flag.Type was already used for the flag's data type (string/bool); CommandArgument.Type carried the identical role under a different name purely because arguments don't have a competing data-type field. Same concept, two field names, driven by an implementation detail rather than a naming decision.
• provides: uses one consistent field name on both arguments and flags, and matches the wording the docs already used to describe the behavior in prose ("this flag provides the stack name").
• This field shipped in a prior release (custom component types, #1904), so the rename is backward-compatible: old configs keep working, marked deprecated, rather than breaking on upgrade.

references

N/A

Summary by CodeRabbit

• New Features

  • Added provides configuration for identifying component and stack values in command arguments and flags.
  • Updated completion and value resolution to use the new metadata.

• Bug Fixes

  • Preserved compatibility with existing type and semantic_type configurations, with the new provides value taking precedence.

• Documentation

  • Updated command configuration guides and examples to use provides.
  • Marked legacy configuration fields as deprecated while documenting continued support.

• Add a json file manager to the Version Tracker (manager: json), configured via options.set: [{path, from}], that writes locked values into JSON files using sjson/gjson — patching only the targeted field and leaving the rest of the document's formatting, key order, and whitespace untouched.
• Fix atmos version track apply to treat an explicit version.files: [] as "manage zero files" instead of silently falling back to each manager's default paths — previously there was no way to configure zero managed files.
• Fix toolchain.lock.yaml, vendor.lock.yaml, and versions.lock.yaml to write with the repo's 2-space YAML indent standard instead of yaml.v3's bare-Marshal 4-space default.
• Add a changelog post and link a roadmap milestone for the new json manager.

why

• Neither the marker manager (needs an adjacent comment annotation, which JSON has no syntax for) nor the template manager (requires hand-maintaining a separate *.tmpl source in sync with the generated file) could cleanly keep a version field in a plain JSON file — such as a package.json or a Claude Code plugin manifest — up to date. This gap was found while wiring Atmos's own agent-skills/.claude-plugin/plugin.json / .claude-plugin/marketplace.json to track Atmos's release version.
• fileRules() used len(Version.Files) > 0, which can't distinguish an omitted version.files key (should fall back to manager defaults) from an explicitly configured empty list (should manage nothing) — both took the same fallback path.
• The three lock-file writers used a bare yaml.Marshal, which drifted their indentation away from every other Atmos-generated YAML file.

references

• Related to the Claude Code plugin version-pinning work (#2895).

Summary by CodeRabbit

• New Features

  • Added a JSON version-file manager for updating configured fields while preserving formatting, key order, whitespace, and unrelated content.
  • Supports multiple fields and files, missing simple paths, and explicitly empty configurations.
  • Planning now reports errors from all selected rules.

• Documentation

  • Added configuration guidance, examples, and blog documentation.

• Improvements

  • Lockfiles now use consistent two-space YAML indentation.
  • Clarified import precedence and default file behavior.
  • Added validation for unsupported paths, mismatches, duplicates, and missing targets.

• Every atmos binary — dev builds, official releases, CI test binaries, and the sharded acceptance-test suite — now builds with GOFIPS140=latest, linking Go's native FIPS 140-3 validated cryptographic module and defaulting the binary to FIPS-enforcing mode (GODEBUG=fips140=on) at runtime. No flag or config change is required.
• Documents the one known gap in docs/prd/fips-140-mode.md: the age/NaCl-based encryption used by declarative secrets management (atmos secret keygen, the SOPS/age backend, and sealed GitHub Actions secret values) sits outside Go's FIPS module boundary and isn't covered by this change.
• Converts scripts/build-atmos.sh to a native Go mage target (magefiles/build.go, Build.Binary), matching the repo's existing mage-based tooling for lint and acceptance-test orchestration, and updates every CI workflow and doc comment that referenced the old script.
• Adds a changelog post and links a shipped milestone on the roadmap.

why

• Operators in regulated environments (federal, financial services, healthcare) are often required to run only FIPS 140-validated cryptography, and Atmos had no way to make that claim for any official binary.
• Verification (build + binary smoke tests, including a real outbound TLS call, plus short-test-suite runs compared against a non-FIPS baseline) found no incompatibility in Atmos's own code — its TLS config, EC curve choice, and randomness usage were already FIPS-compatible patterns; this just makes that enforced by default instead of incidental.
• scripts/build-atmos.sh was the last shell-script build entrypoint in a repo that otherwise self-hosts its build/lint/test tooling through Atmos custom commands and mage targets; converting it removes the shell/Go split and adds proper unit test coverage the shell script never had.

references

• docs/prd/fips-140-mode.md

Summary by CodeRabbit

• New Features

  • Official releases and build outputs now use Go’s FIPS 140-3 cryptographic module by default.
  • atmos version reports the current runtime FIPS status, including structured output.
  • Unified build support now covers standard and cross-platform targets.

• Bug Fixes

  • Builds retry dependency downloads after temporary failures.
  • Unsupported FIPS targets are rejected with clear errors.

• Documentation

  • Added guidance on FIPS mode, runtime overrides, verification, limitations, and platform exclusions.
  • Added an announcement describing the updated cryptographic defaults.

• Tests

  • Expanded coverage for builds, retries, environment settings, and FIPS-enabled binaries.

🚀 Enhancements

• Fix describe affected CI base auto-detection resolving a wrong base commit for merged pull requests: merged PRs now classify what the workflow actually checked out (PR head, merge commit, or synthetic refs/pull/<n>/merge) and anchor the base on event-payload facts (merge_commit_sha^1, or base.sha for fast-forward merges where merge_commit_sha == head.sha), instead of the old merge-base(HEAD, origin/<target>) → HEAD~1 chain that degenerates after the merge.
• Fix describe affected mis-computing BASE worktree paths when the repository lives under a symlinked path (e.g. macOS /tmp): symlink-normalize both sides of the path re-basing, and hard-error (instead of silently guessing) when a config path cannot be represented inside the BASE checkout.
• Add the checkout classification to the Auto-detected CI base log line (checkout=head.sha|merge-commit|synthetic-merge|unknown) so wrong-base reports are diagnosable from a single line.
• New pkg/git helpers (CommitParents, MergeBaseSHAs, FetchCommit), red-first regression tests for every checkout × merge-strategy combination (merge, squash, fast-forward, queue-merged, synthetic, unknown, closed-unmerged), and a new end-to-end test covering base auto-detection through the full affected computation.
• Update the describe affected CLI docs and the native-CI base-resolution PRD to match; add fix-log entries under docs/fixes/.

why

• On a pull_request closed (merged) event with the PR head checked out (the documented workflow), merge-base(HEAD, origin/<target>) collapses to HEAD (the head is now an ancestor of the target) and the HEAD~1 fallback diffs only the PR's final commit. A multi-commit PR whose last commit reverts an earlier org-wide change then reports every component as affected and dispatches a wall of post-merge plan/apply runs; conversely, changes in earlier commits could be silently missed. Observed in production with the zero-config setup.
• Fast-forward/externally-merged PRs (merge_commit_sha == head.sha) would hit the same last-commit-only failure through the new anchor, so they get a dedicated payload-base.sha anchor — caught in an adversarial field-test pass before release.
• Under a symlinked repo path, filepath.Rel mixed git's symlink-resolved repo root with logical CWD-derived config paths, producing an escaping path that — depending on filesystem depth — either scanned a nonexistent BASE (greenfield fallback → everything affected) or clamped back onto the HEAD repo (BASE == HEAD → nothing affected). Both failure modes were silent.
• Every strategy in the old fallback chain was only correct under an assumed checkout that nothing verified; classifying the actual checkout makes the strategy selection provably correct per case and loud when it can't be.

references

• docs/fixes/2026-08-27-describe-affected-merged-pr-base-resolution.md
• docs/fixes/2026-08-27-describe-affected-symlink-base-path-mangling.md
• docs/prd/native-ci/framework/base-resolution.md (updated resolution matrix)
• Builds on the base-resolution self-healing from #2380 and zero-config CI detection from #2241

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved atmos describe affected accuracy for merged pull requests and varied checkout strategies.
  • Fixed affected-component detection for repositories accessed through symlinked paths.
  • Added safeguards for configuration paths outside the repository worktree.
  • Improved CI base-resolution diagnostics by identifying the detected checkout type.

• Documentation

  • Updated CI auto-detection guidance for merged pull requests and merge groups.

• Tests

  • Added end-to-end and regression coverage for merged-PR base resolution and symlinked repositories.

🚀 Enhancements

• Add Condition.MarshalYAML() to pkg/condition/condition.go so a when: condition survives being marshaled back to YAML.
• pkg/condition/condition_test.go: add TestConditionYAMLMarshalRoundTrip (predicate/CEL/all/any-not shapes) and TestConditionYAMLEmptyMarshalRoundTrip, asserting the marshaled-then-decoded value matches the expected shape and evaluates identically to the original across representative facts.
• pkg/project/config/config_baseref_test.go: add TestSaveAndLoadProjectRecord_FieldWhenSurvivesRoundTrip, exercising the real SaveProjectRecord/LoadProjectRecord path with a field-level when: condition (mirroring examples/scaffolding/scaffold.yaml's enable_vendoring/vendor_version pair) and asserting the reloaded condition evaluates correctly.
• No change to condition.Evaluate, CEL compilation, or the JSON marshal/unmarshal paths — out of scope, and unaffected since the fix reuses the same node.value() reconstruction MarshalJSON already relies on.

why

• Condition's only field, node *Node, is unexported. Condition already implements UnmarshalYAML, UnmarshalJSON, and MarshalJSON, but had no MarshalYAML. Without one, yaml.Marshal falls back to reflecting the struct, sees zero exported fields, and writes {} — silently discarding the condition instead of erroring.
• This corrupted atmos scaffold generate's project record (.atmos/scaffold.yaml): a spec.fields[].when CEL string (e.g. "answers.topology == 'multi'") rendered correctly on first generate, but got written back as when: {}. Since --update re-reads that same record on every subsequent run, the project was permanently stuck failing schema validation (expected string, but got object) with no way to self-heal.
• spec.files[].when never showed the same symptom, but not because that path is correct — SaveProjectRecord never copies templateConfig.Spec.Files into the persisted record at all (only Fields, Delimiters, Source, BaseRef, Values are copied), so there's nothing there to corrupt. Verified this holds with a matrix:-expanded files[] entry too: generation succeeds, but spec.files is simply absent from the written record.
• The fix reconstructs the original string/list/map form via node.value() — the same method MarshalJSON already uses. This isn't new behavior: cloneCommand (cmd/cmd_utils.go) already JSON round-trips every custom command's Task.When through this exact normalization on every invocation, so a bare CEL string already canonicalizes to !cel <expr> there today. Extending it to MarshalYAML just makes YAML and JSON serialization consistent with each other.

references

• n/a

Summary by CodeRabbit

• Bug Fixes

  • Preserved field-level YAML conditions when project records are saved and loaded.
  • Ensured predicate, CEL, compound, and empty conditions retain their values during YAML round trips.

• Tests

  • Added coverage confirming condition formatting and evaluation remain consistent after serialization and reloading.

• No changes

what

• Add three feature cards to the homepage "Batteries included" grid: Validation, Scaffolding, and Emulators.
• Each card follows the existing schema (icon, title, description, tag line, doc link) and slots next to its closest existing sibling card (Validation next to Vendoring, Scaffolding next to Toolchain, Emulators next to Workflows & Automation) so the grid still fills to full rows of 4.
• Link targets (/validation/validating, /cli/commands/scaffold/usage, /cli/commands/emulator/usage) were verified against how other docs pages already link to these same destinations internally, not guessed.

why

• These three capabilities already ship in Atmos and have full docs, but weren't represented anywhere on the landing page, understating what the runtime includes out of the box.
• Kept to three additions (not four) so the grid still lands on a clean multiple of 4 cards per row instead of leaving a new single orphaned card in the last row.

references

• N/A

Summary by CodeRabbit

• New Features
  • Added Validation, Scaffolding, and Emulators to the landing page’s battery features.
  • Updated workflow messaging to highlight 35+ step types and revised emulator wording.
• Bug Fixes
  • Improved retries for transient Sigstore trust-root CDN errors while excluding unrelated certificate-fetch failures.
• Documentation
  • Explained how custom commands and workflows can work together as a task runner replacement.
  • Clarified custom command configuration, optional usage, wrapped commands, and examples.
  • Updated the custom commands link to point to the expanded documentation.

what

• Container components (components.container) now resolve build.context, build.dockerfile, and run.mounts[].source the same way Terraform/Helmfile/Kubernetes/Helm components resolve theirs: relative to components.container.base_path joined with the component's own name, via a new precomputed ContainerDirAbsolutePath and a "container" case in the shared component-path resolver.
• components.container.base_path is promoted from an ad hoc, silently-ignored config value into a real, typed Components.Container.BasePath field.
• Container components gain the same just-in-time source: provisioning as Terraform/Helmfile/Kubernetes/Helm — a component declaring a source is auto-vendored into a workdir, which then anchors build/mount paths instead of the static base path.
• Removed the now-redundant bespoke container.Config/DefaultConfig()/parseConfig(), and fixed a hardcoded "components/container" literal in describe_stacks.go that ignored any configured override.
• Regenerated the atmos.yaml JSON schema, updated the container CLI docs and the atmos-container agent skill, and added a changelog post + roadmap milestone.

why

• build.context/build.dockerfile were passed to docker build/podman build completely unanchored, so they silently resolved against whatever directory atmos happened to be invoked from instead of the project — working by accident only when run from the repo root.
• run.mounts[].source anchored to the bare project root rather than the component itself, and components.container.base_path had no effect anywhere despite being accepted as valid config.
• Every other component type already has a consistent, CWD-independent path-resolution mechanism (base_path + component:/metadata.component) plus JIT source provisioning; containers were the one component kind never wired into it.

references

• N/A

Summary by CodeRabbit

• New Features

  • Added configurable container component base paths, defaulting to components/container.
  • Relative build contexts and mount sources now resolve from the component directory; Dockerfiles resolve from the build context.
  • Added automatic provisioning for container components using source: when needed.

• Documentation

  • Added guidance on path resolution, configuration, migration, and source provisioning.
  • Updated the product roadmap to reflect the shipped functionality.

what

test-required (the legacy compatibility shim that aliases the sharded test matrix under the three historical required-check names) checked needs.test.result, which is a single aggregated verdict across the entire test matrix (3 OSes × 10 shards). A failure in any one shard on any one OS flipped that aggregate to failure, so all three aliases (Acceptance Tests (linux/macos/windows)) failed together even when only one OS actually had a failing shard.

This PR rewrites test-required to query the run's actual per-job results via gh api .../actions/runs/.../jobs, filtered by OS, so each alias only fails when a shard belonging to its own OS failed. It also stops gating the macos alias on terraform-registry-cache (whose matrix only has linux/windows legs and has no macos job to report on), which had the same cross-OS aggregation bug.

why

Observed on #2972: windows shard 2/10 failed after 57s, and Acceptance Tests (linux), (macos), and (windows) all failed within 3-4s as sympathetic failures with no real linux/macos test failures, forcing unnecessary re-runs/investigation of unaffected OSes.

references

• Observed on #2972

what

• Relocate the default golangci-lint cache and tmp directories from inside each worktree (.golangci-cache/, .golangci-tmp/) to the OS user cache directory: <user-cache>/atmos-lint/<worktree-hash>/{cache,tmp} (~/Library/Caches/atmos-lint/... on macOS).
• The <worktree-hash> (first 12 hex chars of SHA-256 of the absolute worktree path) preserves #2701's per-worktree isolation of golangci-lint's single-instance lock — the dirs just no longer live under the worktree tree.
• ATMOS_LINT_SHARED_CACHE=1 opt-out and explicit GOLANGCI_LINT_CACHE overrides behave exactly as before.
• Tests updated/added: new-location assertions, hash determinism + cross-worktree non-collision, user-cache-dir failure propagation.
• Adds docs/fixes/2026-08-24-fsmonitor-worktree-saturation.md with the full measured diagnosis.

why

#2701 put a 156MB / ~37k-file cache that churns on every lint run inside each worktree — directly under any filesystem watcher observing that tree (git fsmonitor, Conductor's watchexec). At multi-worktree scale this saturated macOS FSEvents: git status measured 2.9s–timeout (>2min) with fsmonitor vs 0.04–0.15s without, and every pre-commit run pays that tax dozens of times, stretching commits to minutes. Moving the churn outside the watched tree makes this impossible to re-trigger on any machine, regardless of watcher configuration.

Measured after the fix: cold lint:precommit 9.1s, warm 1.5s, no cache dirs created in the worktree; a full commit through all pre-commit hooks + signing completes in ~5s.

references

• #2701 (perf(lint): isolate golangci-lint cache and lock per worktree) — introduced the in-worktree location this PR relocates; its lock-isolation intent is preserved
• docs/fixes/2026-08-24-fsmonitor-worktree-saturation.md — full diagnosis, timeline, and machine-level remediation notes

Summary by CodeRabbit

• Bug Fixes

  • Improved linting in Git worktrees by storing cache and temporary files in isolated user-cache locations.
  • Reduced unnecessary file-monitor activity caused by lint-related file churn.
  • Preserved support for shared caches and explicitly configured cache locations.
  • Improved error handling when cache locations cannot be resolved or created.
  • Added safeguards to keep cache data separated between worktrees.

• Documentation

  • Added troubleshooting guidance for worktree file-monitor saturation and remediation steps.

what

• Set "moby": false on the docker-outside-of-docker devcontainer feature in .devcontainer/devcontainer.json.

why

The Codespaces Prebuilds workflow (prebuild) fails on every push to main. Example failed run: https://github.com/cloudposse/atmos/actions/runs/32431458655/job/96623702606

The base image mcr.microsoft.com/vscode/devcontainers/base:debian now resolves to Debian 13 (trixie), which does not package moby-cli. The docker-outside-of-docker feature defaults to moby: true and errors out during the prebuild image build:

(!) The 'moby' option is not supported on debian 'trixie' because 'moby-cli'
    and related system packages are not available in that distribution.
(!) To continue, either set the feature option '"moby": false' or use a
    different base image (for example: 'debian:bookworm' or 'ubuntu-24.04').
ERROR: Feature "Docker (docker-outside-of-docker)" failed to install!

Setting moby: false makes the feature install Docker CE instead. This is safe and non-redundant: the devcontainer Dockerfile already configures Docker's official apt repo and installs docker-ce/docker-ce-cli, so no moby packages were ever needed — the feature only wires up the forwarded host Docker socket.

references

• Failed run: https://github.com/cloudposse/atmos/actions/runs/32431458655/job/96623702606
• Feature docs: https://github.com/devcontainers/features/tree/main/src/docker-outside-of-docker

Summary by CodeRabbit

• Chores
  • Updated the development container configuration to install Docker CE instead of Moby on Debian 13.

what

• Bump the Docker Build step in .github/workflows/build.yml from cloudposse/github-action-docker-build-push v3.1.0 (02993d67) to v3.2.1 (ff59bd5).

why

• The release / Build and push Docker image for Atmos CLI job has been failing on the post-build Docker Inspect summary step with jq: error (at inspect.json:79): Cannot iterate over null (null) → exit code 5, even though the image builds and pushes fine.
• Root cause was in the action itself: its summary step fed docker inspect fields (.Config.Entrypoint, .Config.Cmd, .Config.Env, .RootFS.Layers) straight into jq's join/.[]/to_entries, all of which iterate. Atmos's image is FROM debian:trixie-slim with no ENTRYPOINT, so .Config.Entrypoint is null and jq aborts; under the default bash -e shell that fails the whole step.
• Fixed upstream in cloudposse/github-action-docker-build-push#111 (guards each iterating expression with // []), released as v3.2.1. Verified ff59bd5 contains all four guards. This bump pins Atmos to that release so the release job's summary no longer crashes.

references

• Failing run: https://github.com/cloudposse/atmos/actions/runs/32415649296/job/96577335200
• Upstream fix: cloudposse/github-action-docker-build-push#111
• Release: https://github.com/cloudposse/github-action-docker-build-push/releases/tag/v3.2.1

Summary by CodeRabbit

• Chores
  • Updated the Docker build workflow to use a newer action version, improving build pipeline maintenance and reliability.

🚀 Enhancements

what

• Restore two public functions that external consumers of the Atmos Go library depend on:
  • pkg/aws.ExecuteAwsEksUpdateKubeconfig — thin public wrapper delegating to internal/exec.ExecuteAwsEksUpdateKubeconfig.
  • pkg/utils.JSONToMapOfInterfaces — decodes a JSON string into a schema.AtmosSectionMapType (errors on non-object top-level values, unlike ConvertFromJSON).
• Add tests covering both restored functions (which also keep them out of the deadcode -test set).
• Add a fix doc under docs/fixes/.

why

• PR #2608 (refactor(utils): drop dead helpers ...) removed both functions because the deadcode sweep reported zero callers inside the Atmos repo. That analysis does not see external module consumers, so these were public-API removals, not truly dead code.
• cloudposse/terraform-provider-utils embeds the Atmos Go library and relies on both:
  • its utils_aws_eks_update_kubeconfig data source calls pkg/aws.ExecuteAwsEksUpdateKubeconfig;
  • its test suite calls pkg/utils.JSONToMapOfInterfaces.
• As a result, the provider fails to build against Atmos v1.222.0+ (the kubeconfig executor moved into internal/exec, which external modules cannot import; JSONToMapOfInterfaces was deleted). This pins the provider to v1.221.1 and prevents it from tracking newer Atmos releases — which matters because the provider must embed the same deep-merge semantics as the paired Atmos CLI.
• Restoring these thin wrappers unblocks the provider upgrade with no behavior change. Verified by building terraform-provider-utils against this branch (local replace + atmos@v1.226.1): go build ./..., go vet ./internal/..., and its full unit/library test suite all pass. deadcode -test ./... no longer reports either function.

references

• Regression introduced by #2608
• Downstream consumer: https://github.com/cloudposse/terraform-provider-utils (utils_aws_eks_update_kubeconfig data source, internal/convert tests)
• See docs/fixes/2026-08-25-restore-public-provider-api-wrappers.md

Summary by CodeRabbit

• New Features

  • Restored public support for generating Amazon EKS kubeconfig files.
  • Added a public utility for converting JSON objects into map values.

• Bug Fixes

  • EKS kubeconfig generation now reports conflicts between profile and role settings.
  • JSON conversion now rejects malformed, empty, null, and other non-object input.

• Documentation

  • Documented public API usage, validation behavior, and safeguards against accidental removal.

what

• Fixes defaultCliConfig (the config used when no atmos.yaml is discoverable) to state settings.terminal.help.filter: true, matching the journaled/SetDefault value.
• Fixes a blind spot in TestJournalAgreesWithDefaultCliConfig that treated "field absent from the struct" and "field explicitly serialized as false" as equivalent, letting this exact class of drift through silently.
• Adds TestLoadConfigNoAtmosYamlDefaults, a regression test that loads config from a directory with no atmos.yaml anywhere — the one fallback path every existing edition/help test skips.

why

• Bare --help was regressing to the full --help=all output (all flags, no focused view, no --help=usage/--help=all hint) whenever no atmos.yaml was discoverable — e.g. running atmos --help right after install or from outside a project directory.
• Root cause: defaultCliConfig's Terminal literal never set Help, so it zero-valued to HelpSettings{Filter: false}. Since the field has no omitempty tag, that explicit false was marshaled into Viper's CONFIG layer and silently overrode the intended true from SetDefault, which only reaches the lower-priority DEFAULT layer. Introduced in #2762, which added the journal entry but missed the matching defaultCliConfig entry.
• Verified the fix and both new/adjusted tests by reverting the fix locally and confirming they fail without it, then pass with it restored; also confirmed at the CLI level that atmos --help (no config file) now differs from --help=all and shows the expected hint.

references

• Introduced by #2762 ("feat: add date-anchored default editions")

Summary by CodeRabbit

• New Features

  • Focused CLI help output is now enabled by default, making help information more concise and relevant.

• Bug Fixes

  • Default help behavior is applied consistently even when no atmos.yaml configuration file is available.

• Tests

  • Improved configuration validation to correctly recognize explicitly set values, including false, empty strings, and 0.
  • Updated timing checks to better accommodate scheduling delays across environments, including Windows CI.

what

• Replace pkg/provisioner/workdir's injective character-escaping scheme (-->-h, /->-s, \->-b) with a <stack>-<sanitized-name>-<hash> naming scheme for .workdir/<type>/... directories.
• Add migration for both previously-shipped legacy naming formulas so existing on-disk workdirs get renamed forward instead of orphaned.
• Add a fail-closed identity check when reusing an existing hash-suffixed workdir, guarding against the (astronomically unlikely) hash-collision case.
• Update call sites and tests across pkg/provisioner/workdir, pkg/provisioner/source, pkg/component, internal/terraform_backend, pkg/terraform/output, and tests/ that asserted on the old escaped naming.

why

• Component/version names containing hyphens (e.g. vpc-flow-logs-1.226.1) were mangled into unreadable directory names like vpc-hflow-hlogs-h1.226.1, since - was both the most common character in real component names and the encoding's own escape marker.
• A hash-suffixed prefix keeps directory names human-readable for the common case while still guaranteeing collision-free uniqueness, without relying on a hand-rolled, hard-to-verify injective-escaping proof.

references

• Fix log: docs/fixes/2026-08-22-workdir-naming-hash-suffix.md

Summary by CodeRabbit

• New Features

  • Workdir names now use sanitized component names with an 8-character hash suffix to prevent collisions.
  • Legacy workdir formats can be migrated automatically.
  • Existing workdirs are validated before reuse to prevent identity mismatches.
  • workdir clean --all --dry-run lists workdirs without deleting them.

• Bug Fixes

  • Improved workdir discovery, migration, and component-instance path handling.
  • Build dependency downloads now retry transient failures.

• Documentation

  • Updated workdir naming, cleanup, listing, and description guidance.

what

• Pin atmos scaffold generate --update's default 3-way-merge base ref to the commit
  actually created by the initial --git generation, instead of always defaulting to
  live HEAD.
• Exclude .git directories when reading a template's files, for both local-directory
  templates and git:: remote sources fetched into a temp dir.
• Fix atmos scaffold generate --dry-run to match real generation exactly: skip
  directory entries, honor spec.files[].when conditions, and render file paths with
  the template's own spec.delimiters.

why

• --update could silently discard a customization a user had already committed to the
  generated project, as long as the template's own change landed on a different line --
  because the merge always diffed against live HEAD, a committed edit became
  indistinguishable from the "base" content and the freshly rendered template silently
  won with no conflict reported.
• A template source that was itself a git checkout (or fetched via git::) leaked its
  own .git internals (objects, refs, a config pointing at the source repo) into every
  generated project.
• --dry-run reported more files than a real run actually produces (directories counted
  as files, when: false files listed anyway, custom-delimiter paths shown unrendered),
  making the preview unreliable for reviewing what a generation would do before running it.
• All three were reported by a client evaluating the ([EXPERIMENTAL]) scaffold feature,
  with exact repro steps; none had existing tracked issues. A fourth reported bug
  (hardcoded default template delimiters in three call sites) is intentionally left out of
  this PR -- the client has their own patch and will submit it separately.

references

• Fix record: docs/fixes/2026-08-24-scaffold-update-git-dryrun-fixes.md

Summary by CodeRabbit

• New Features

  • Enhanced scaffold generation with matrix expansion, conditional files, custom delimiters, target overrides, and update merging.
  • Added clearer dry-run previews that validate generation without writing files, creating directories, running hooks, or saving project records.

• Bug Fixes

  • Scaffold updates now preserve customizations using the correct pinned base revision.
  • Prevented .git contents from being copied into generated projects.
  • Improved target resolution, remote template handling, and metadata error reporting.

• Documentation

  • Updated guidance on scaffold updates, dry-run behavior, validation, and known limitations.

what

• atmos aws ecr login / atmos azure acr login ambient-credential fallback (no Atmos identity
  configured) now returns a rich, actionable error when the underlying cloud SDK fails to retrieve
  credentials (e.g. EC2 IMDS timeout, Azure managed identity failure), with an explanation and a
  hint to run login --identity <name> or configure via.identity.
• Fixed bare --identity (no value) failing with flag needs an argument instead of showing the
  interactive identity selector, on 6 commands: custom commands (atmos.yaml commands:),
  describe, list, aws ecr login, aws eks token, and azure aks token. Each had hand-rolled
  its own --identity flag registration instead of using the shared flags.WithIdentityFlag()
  builder that ~150 other commands already use, so each silently lost the NoOptDefVal wiring that
  makes bare --identity legal and triggers the picker.
• Exported auth.ResolveSelectedIdentity (pkg/auth/manager_helpers.go) so the
  sentinel-to-interactive-picker resolution logic lives in one place instead of being duplicated
  (aws ecr login) or missing entirely (the other five commands).

why

• A user hit both issues running a downstream custom command (atmos app build): first
  --identity (bare) rejected as a usage error instead of prompting, and separately — once
  ambient AWS credentials were tried as a fallback — a bare EC2 IMDS timeout with no indication
  that configuring an Atmos identity was the fix.
• The --identity flag exists as a single, centrally-defined flag specifically so this class of
  bug can't happen; these 6 commands were the stragglers that never got migrated onto that shared
  definition, so the bug had to be independently rediscovered and patched (see the ad-hoc
  NoOptDefVal fix already present on aws ecr login) instead of being fixed once.

references

• docs/fixes/2026-08-20-ecr-acr-ambient-credential-identity-hint.md
• docs/fixes/2026-08-21-identity-flag-noOptDefVal-consolidation.md

Summary by CodeRabbit

• New Features

  • Bare --identity now opens interactive identity selection across supported AWS, Azure, EKS, listing, description, and custom commands.
  • Selected identities are consistently applied to subsequent authentication and operations.

• Bug Fixes

  • Improved ECR and ACR authentication errors with actionable identity configuration guidance.
  • Preserved underlying authentication and selection errors for easier troubleshooting.

• Documentation

  • Added guidance covering interactive identity selection and ambient credential troubleshooting.

what

• Routes every access to the process-wide global Viper singleton through a new mutex-guarded pkg/config.GlobalViper() wrapper (SafeViper), instead of calling viper.GetViper()/viper.Set/viper.Get* directly — mirroring the embedded-mutex pattern already used by pkg/io/pkg/ui.
• Fixes pkg/hooks.GetHooks to forward the AtmosConfig it already received into ExecuteDescribeComponentParams, removing a redundant second, independently concurrent config load per hook invocation.
• Closes a second, independently racy package-level slice (mergedConfigFiles in pkg/config/load.go) by wrapping it in its own mutex-guarded tracker.
• Adds pkg/config/load_concurrent_test.go, a -race-driven regression test that spins up concurrent LoadConfig calls against a real fixture and reproduces the original panic on unfixed code.
• Minor cleanup: bridgeVendorUpdaterConfig now fetches GlobalViper() once instead of once per Set call, and a new ciFlagKey constant replaces 10 duplicated "ci" string literals in cmd/terraform/utils.go (surfaced by golangci-lint's add-constant check once those lines were touched).

why

• atmos terraform ... --max-concurrency 3 (and even 2) could panic with fatal error: concurrent map writes inside viper.(*Viper).Set, reported from production usage. Root cause: pkg/config.LoadConfig bridges profiles.base_path and vendor.update.*/vendor.ci.* into the process-wide global Viper singleton on every call, with zero locking (spf13/viper has no internal synchronization), while the DAG scheduler runs LoadConfig concurrently — once per graph node — whenever --max-concurrency > 1.
• GetHooks was also triggering a second, entirely redundant InitCliConfig/LoadConfig call per node because it never forwarded the AtmosConfig it was already given, doubling the exposure to the race for no reason.
• The regression test proves the fix: run against the pre-fix code under go test -race, it reliably reproduces the exact viper.(*Viper).Set race reported in production; against the fixed code it passes clean.

references

• Reported in Slack by two engineers hitting the same panic at --max-concurrency 2 and 3.

Summary by CodeRabbit

• Bug Fixes

  • Improved configuration handling during concurrent operations, preserving environment-key casing and preventing cross-load contamination.
  • Ensured hooks use the active configuration when describing components.
  • Standardized CI mode and profile settings detection across commands.
  • Explicit --ci=false now overrides CI environment settings and automatic CI detection.
  • Improved reliability when reading shared configuration during shell and command execution, including masking settings.

• Tests

  • Added coverage for concurrent configuration loading, CI precedence, shared configuration access, and configuration-aware hook execution.

Summary

TF_CLI_ARGS_apply configured through atmos.yaml no longer reaches Terraform-exec's internal output command. Post-apply output-store hooks can retrieve and publish the declared Terraform output after a successful apply.

Why

Terraform-exec rejects manual command-specific argument variables during its output invocation. Atmos filtered inherited variables but restored them from the resolved component environment. The output path now ignores TF_CLI_ARGS and TF_CLI_ARGS_* while preserving normal environment variables and TF_VAR_* values.

Validation

• Added a regression test for apply and plan CLI arguments while preserving TF_VAR_*.
• go build ./...
• atmos fix coverage origin/main
• Patch lint: 0 issues.

Closes #2990

Summary by CodeRabbit

• Bug Fixes

  • Fixed Terraform output retrieval failures caused by command-specific CLI argument environment variables.
  • Preserved supported component variables, including TF_VAR_* values, while excluding TF_CLI_ARGS settings from output processing.

• Documentation

  • Added documentation describing the fix and its expected behavior.

what

• atmos packer now sets up Atmos Auth the same way terraform and helmfile do: it creates and authenticates the component AuthManager, passes it to ProcessStacks, and injects the resolved identity's credentials into the packer subprocess environment before executing.
• Extracted the credential-injection helpers (resolveDefaultIdentity and the renamed prepareComponentAuthEnvironment, formerly prepareHelmfileAuthEnvironment) into internal/exec/utils_auth.go so helmfile and packer share one path instead of duplicating it.
• Added regression tests (internal/exec/packer_auth_test.go) via two test seams: one asserts a non-nil AuthManager is passed to ProcessStacks; the other asserts an injected credential reaches the packer subprocess env.
• Added a fix record under docs/fixes/.

why

• atmos packer build ran completely unauthenticated when relying on Atmos Auth. internal/exec/packer.go called ProcessStacks(..., nil) (nil AuthManager) and never called PrepareShellEnvironment, so no AWS credentials ever reached the packer process. Its datasources failed with:

  Error: Datasource.Execute failed: No valid credential sources found
  

• Both other component executors already do this — terraform via setupTerraformAuth + auth.TerraformPreHook, helmfile via SetupComponentAuthForCLI + credential injection — so packer was the odd one out, even though the AuthManager interface docstring explicitly lists Packer as a supported subprocess.

• Verified against a real workload: atmos packer build <component> -s <stack> now proceeds into the AMI build (VPC prevalidation, keypair creation, etc.) where the stock binary failed with the credential error.

references

• Mirrors the existing helmfile auth flow in internal/exec/helmfile.go.
• AuthManager contract: pkg/auth/types/interfaces.go (PrepareShellEnvironment — "Use this for all subprocess invocations: Terraform, Helmfile, Packer, ...").
• Fix doc: docs/fixes/2026-08-23-packer-atmos-auth-credential-injection.md.

Summary by CodeRabbit

Bug Fixes

• atmos packer build now honors configured authentication settings.
• Credentials for authenticated components are automatically resolved and provided during Packer builds.
• Authentication behavior is now consistent across supported component workflows.
• Added regression coverage to improve reliability and prevent authentication regressions.

Documentation

• Added guidance for configuring authentication when using Packer builds.
• Updated workload and continuous integration examples with clearer, generic descriptions.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.

🚀 Feature Preview Release

This is a feature preview based on an open pull request. It is intended for testing artifacts and validating functionality before the feature is merged.