Implement a ttl (time-to-live) field on component source configuration to control how long cached JIT-vendored sources are reused before re-pulling from the remote. This solves the problem of stale caches when using floating refs (branches) without requiring manual --force flags.

Key Feature: Declarative cache expiration policy. Set ttl: 0s for active development (always fresh), ttl: 1h for team collaboration (hourly refresh), or omit TTL for infinite cache (backward compatible).

Problem Solved

When JIT-vendored components use floating refs like version: "main", Atmos skips re-pulling because the version string in metadata hasn't changed—it's still "main" even though upstream content has. Developers must manually delete .workdir/ or run source pull --force.

Solution

Add optional ttl field to source configuration. When set, the source provisioner compares the workdir's update timestamp against the TTL. If expired, the source is re-pulled automatically.

# Per-component override (stack manifest)
components:
  terraform:
    my-module:
      source:
        uri: git::https://github.com/org/repo.git
        version: main
        ttl: "0s"  # Always re-pull

# Global default (atmos.yaml)
components:
  terraform:
    source:
      ttl: "1h"  # Re-pull if older than 1 hour

Changes

• ✅ Add TTL field to VendorComponentSource schema
• ✅ Add TerraformSourceSettings struct with global TTL default
• ✅ Parse ttl from source maps in extract.go
• ✅ Implement TTL expiration check in needsProvisioning()
• ✅ Support per-component override and global defaults
• ✅ Handle zero TTL explicitly (always expires)
• ✅ Comprehensive unit tests for all TTL behaviors

Documentation

• ✅ Updated terraform, helmfile, and packer source command docs with ttl field
• ✅ Added "Cache TTL for Floating Refs" section to source-based versioning design pattern
• ✅ Created PRD explaining problem, solution, and architecture (docs/prd/source-cache-ttl.md)
• ✅ Created blog post with user-facing guidance (website/blog/2026-03-03-source-cache-ttl.mdx)
• ✅ Updated roadmap with shipped milestone

Test Plan

• Unit tests for TTL behavior: zero TTL, relative TTL with recent/old timestamps, no TTL
• Integration tests for component sourcing with TTL
• Tests for global TTL default merging
• Code compiles: go build ./...
• Tests pass: go test ./pkg/provisioner/source/...
• Linting passes: make lint
• Website builds: cd website && npm run build

Related

Fixes #2135

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added source cache TTL for JIT‑vendored components. Configure per‑component or via a global default; "0s" forces re‑pull, other durations (e.g., "1h", "7d") trigger automatic refresh, unset = indefinite cache. Global default merges with per‑component TTL (per‑component wins).

• Documentation

  • New docs, examples, a blog post, and CLI doc updates demonstrating TTL usage for Terraform, Helmfile, and Packer and recommended workflows.

• Tests

  • Added unit tests for TTL parsing, invalid TTL handling, default merging, and TTL-driven provisioning decisions.

Implement vendor targets as both strings and maps with optional version overrides, enabling multiple versions of the same component from a single source entry.

• New AtmosVendorTarget type with custom YAML unmarshaling that accepts both string and map syntax
• Per-target version re-resolution: When a target specifies its own version, the source URL template is re-resolved with that version
• List vendor command support: Updated to show correct paths for per-target version overrides
• JSON Schema update: Changed targets.items from single string type to oneOf supporting both syntaxes
• 14 comprehensive tests: 9 unmarshal tests + 5 processTargets unit tests covering all scenarios
• Blog post and roadmap: Announced feature and updated roadmap milestone

why

Vendor targets syntax was documented but never implemented—a hallucination from commit d549991. Previously, vendoring multiple versions of the same component required duplicating the entire source entry. Per-target overrides allow a single source definition to vendor multiple versions cleanly:

sources:
  - component: vpc
    source: "github.com/cloudposse/terraform-aws-vpc.git///?ref={{.Version}}"
    version: "2.1.0"
    targets:
      - "components/terraform/vpc"
      - path: "components/terraform/vpc/{{.Version}}"
        version: "3.0.0"

This is backward compatible—existing string-based targets continue working identically while new map syntax enables flexible per-target version management.

references

• Documented syntax from: website/docs/design-patterns/version-management/vendoring-components.mdx lines 260-264
• Follows Tasks/Task unmarshaling pattern from pkg/schema/task.go
• All tests passing: schema unmarshal tests, processTargets unit tests, list vendor tests, vendor_utils tests

Summary by CodeRabbit

• New Features

  • Per-target version overrides for vendor configs: targets can be strings or objects with path+optional version; per-target versions re-resolve source URLs, affect package naming, target path templates ({{.Version}}, {{.Component}}), and source locality classification.

• Schema

  • Vendor targets schema now accepts either a string path or an object with path and optional version.

• Documentation

  • Blog post and roadmap entry added with examples.

• Tests

  • Extensive unit tests covering parsing, templating, and per-target resolution.

Add Product Requirements Document for enhancing the aws/user identity with browser-based OAuth2 authentication as a fallback credential source.

• Extends existing aws/user identity (NOT a new provider type)
• Three-tier credential resolution: YAML → Keychain → Browser webflow
• Zero-config authentication using AWS console credentials
• Supports headless/remote mode for servers without browsers
• Native SDK implementation (no AWS CLI dependency)

why

DEV-3829 tracks the implementation of browser-based authentication. This approach:

• Provides seamless fallback when no static credentials configured
• Maintains backward compatibility with existing configurations
• Eliminates need for long-term IAM access keys
• Enables zero-config onboarding for new users

references

• Linear: DEV-3829
• AWS Blog: Simplified developer access

Summary by CodeRabbit

• New Features

  • Browser-based OAuth2 (PKCE) fallback for aws/user enabling interactive and headless remote authentication when no static credentials are present.

• Documentation

  • New product requirements and user-facing docs covering overview, user journeys, credential lifecycle, configuration examples, security, testing, rollout, and success metrics.

• Roadmap

  • Planned milestone added for browser-based OAuth2 auth (Q1 2026).

• Add comprehensive PRD for EKS kubeconfig authentication integration
• Define integration pattern following ECR PR #1859
• Document configuration schema, AWS SDK usage, and CLI command design
• Enhance existing atmos aws eks update-kubeconfig command (not create new atmos auth command)

why

• Establishes design before implementation to ensure alignment with ECR integration pattern
• Provides reference for implementation of dependent components (EKS integration, kubeconfig manager)
• Uses existing atmos aws command namespace to avoid leaking AWS-specific commands into atmos auth
• Enables parallel development once ECR PR #1859 is merged

references

• Relates to: DEV-3815
• Depends on: ECR Authentication PR #1859

Summary by CodeRabbit

• Documentation
  • Added a comprehensive PRD for EKS kubeconfig integration with Atmos authentication, covering architecture and configuration schemas, CLI kubeconfig workflows (integration and explicit cluster modes), multi-cluster support and merge behavior, XDG-compliant kubeconfig storage, AWS integration approach, generated kubeconfig output and environment handling, testing strategy, security considerations, deployment/metrics, and proposed future enhancements.

• Fix .claude-plugin/marketplace.json schema that caused /plugin marketplace add cloudposse to fail with Invalid schema: plugins.0.source: Invalid input
• Change source from "." to "./agent-skills" — the source field must point to the directory containing `.claude-plugin/plugin....

• Stack processor now extracts and merges dependencies from global (Scope 1) and component-type (Scope 2) sections
• Component-type level dependencies defined via terraform.dependencies.tools (and helmfile/packer/ansible equivalents) now flow through to component configs
• Toolchain auto-install is now triggered for mixin-pattern dependencies defined at the component-type level
• Dependencies merge chain now includes all 3 scopes: global/component-type → base component → component instance

why

The bug prevented users from configuring dependencies at the component-type level (Scope 2) via mixin patterns like:

terraform:
  dependencies:
    tools:
      terraform: "1.6.0"

The stack processor dropped this data before it reached the toolchain resolver, so auto-install never triggered. Users reported exec: "terraform": executable file not found in $PATH errors when they configured Scope 2 dependencies.

This fix ensures all 3 scopes of dependencies are properly extracted, merged with correct precedence, and propagated through to component sections where the resolver can access them.

references

Fixes the bug discussed in the Slack conversation where Jonathan Rose configured Scope 2 dependencies but toolchain auto-install wasn't triggered.

Changes:

• errors/errors.go: Added 5 sentinel errors for dependencies validation
• internal/exec/stack_processor_process_stacks_helpers.go: Added GlobalDependencies field to ComponentProcessorOptions
• internal/exec/stack_processor_process_stacks.go: Extract and merge dependencies from all 3 scopes, pass through opts builders
• internal/exec/stack_processor_merge.go: Updated merge chain to include global dependencies with lowest priority
• tests/: Added 2 integration tests proving Scope 2 dependencies trigger toolchain auto-install

Summary by CodeRabbit

• New Features

  • Declare dependencies at global, component-type, and component scopes; these are merged with defined precedence and propagated into component processing.

• Chores

  • Added validation error sentinels to surface invalid dependencies sections across component types.

• Tests

  • Added integration fixtures and unit tests covering dependency propagation, precedence, inheritance, binary/toolchain handling, and invalid-section error paths.

what

• Add ignore rule to the shared goreleaser config (.github/goreleaser.yml) to exclude the windows/arm (32-bit ARM) build target
• Prevents "unsupported GOOS/GOARCH pair windows/arm" build failures for any org repo using Go 1.24+

why

• Go 1.24 (February 2025) deprecated the windows/arm port, and Go 1.25+ removed it entirely. Any repo that upgrades past Go 1.23 and uses this shared goreleaser config will fail during the release build after spending ~33 minutes compiling the other 13 targets
• The ignore rule is harmless for repos still on Go < 1.24 — goreleaser simply skips a target that would otherwise build successfully. No binaries are lost for any currently-supported platform
• windows/arm (32-bit ARM on Windows) had negligible real-world usage — Windows on ARM devices run 64-bit Windows 11 (windows/arm64), which remains supported

references

• Go 1.24 release notes — Ports: "Go 1.24 is the last release that supports building for 386 and arm GOOS targets on Windows"
• Go issue #67001: Remove windows/arm port
• GoReleaser ignore docs: filtering unsupported GOOS/GOARCH pairs
• cloudposse/.github#246

Summary by CodeRabbit

• Chores
  • Excluded Windows ARM 32-bit builds from release distribution.

what

• Added 21 AI agent skills following the Agent Skills Open Standard and the AGENTS.md standard (Linux Foundation AAIF)
• Skills packaged as a single Claude Code plugin (atmos@cloudposse) -- one install command, all 21 skills
• Added Claude Code plugin marketplace manifest (.claude-plugin/marketplace.json) and plugin manifest (agent-skills/.claude-plugin/plugin.json)
• Added AGENTS.md skill-activation router for cross-tool compatibility (Codex, Gemini, Cursor, Windsurf, Copilot)
• Added 21 .claude/skills/ symlinks for contributor auto-discovery when working in the Atmos repo
• Added website documentation at website/docs/integrations/ai/agent-skills.mdx (skill reference) and website/docs/projects/setup-editor/ai-assistants.mdx (tool setup)
• Added blog post at website/blog/2026-02-27-ai-agent-skills.mdx
• Added PRD at docs/prd/atmos-agent-skills.md
• Added CI workflow (.github/workflows/validate-agent-skills.yml) to validate skill structure, size limits, frontmatter, and code fence tags
• Updated roadmap and sidebars

Skills (21 total, 1 plugin)

Each skill follows a 3-tier progressive disclosure pattern: AGENTS.md router → SKILL.md instructions → references/*.md deep dives.

All 21 skills live in a flat agent-skills/skills/ directory:

atmos-ansible, atmos-auth, atmos-components, atmos-config, atmos-custom-commands, atmos-design-patterns, atmos-devcontainer, atmos-gitops, atmos-helmfile, atmos-introspection, atmos-packer, atmos-schemas, atmos-stacks, atmos-stores, atmos-templates, atmos-terraform, atmos-toolchain, atmos-validation, atmos-vendoring, atmos-workflows, atmos-yaml-functions

Claude Code Plugin Marketplace

Install with two commands:

/plugin marketplace add cloudposse/atmos
/plugin install atmos@cloudposse

Team auto-discovery via .claude/settings.json:

{
  "enabledPlugins": {
    "atmos@cloudposse": true
  }
}

Other AI Tools

For Gemini CLI, OpenAI Codex, Cursor, Windsurf, and GitHub Copilot, use Atmos vendoring:

# vendor.yaml
apiVersion: atmos/v1
kind: AtmosVendorConfig
metadata:
  name: atmos-agent-skills
  description: Vendor Atmos AI agent skills
spec:
  sources:
    - component: "agent-skills"
      source: "github.com/cloudposse/atmos.git//agent-skills?ref={{.Version}}"
      version: "main"
      targets:
        - "agent-skills"

atmos vendor pull --component agent-skills

Open Standards

Built on two open standards:

• AGENTS.md -- Cross-tool instruction file (OpenAI, Google, Cursor, Linux Foundation AAIF)
• Agent Skills -- Skill packaging format (Anthropic, Microsoft, OpenAI, GitHub)

why

AI coding assistants need domain-specific context to generate correct Atmos configurations. Without skills, they guess at YAML format, use wrong CLI flags, and miss Atmos patterns like deep merging, abstract components, and YAML functions. Skills provide structured, up-to-date knowledge directly in the repository so AI tools generate accurate guidance.

references

• Agent Skills Specification
• AGENTS.md Standard
• PRD: docs/prd/atmos-agent-skills.md
• Documentation: AI Agent Skills | Configure AI Assistants

what

• Add a new !aws.organization_id YAML function that retrieves the AWS Organization ID by calling the AWS Organizations DescribeOrganization API
• New pkg/aws/organization/ package with Getter interface, per-auth-context caching with double-checked locking, and mock support
• Full integration with Atmos Authentication — uses credentials from the active identity when available, falls back to standard AWS SDK credential resolution
• Handles AWSOrganizationsNotInUseException with a clear error message when the account is not in an organization
• Added ErrAwsDescribeOrganization sentinel error
• Updated Go toolchain references to 1.26

why

• Users need to reference the AWS Organization ID in stack configurations for governance, tagging, cross-account trust policies, and SCP scoping
• Currently the organization ID must be hardcoded or retrieved through workarounds
• This is the Atmos equivalent of Terragrunt's get_aws_org_id() function
• Closes #2073

references

• closes #2073
• AWS API: DescribeOrganization
• Terragrunt equivalent: get_aws_org_id()

Summary by CodeRabbit

Release Notes

• New Features

  • Added !aws.organization_id YAML function to retrieve AWS Organization ID from stack configurations with automatic per-invocation caching.

• Chores

  • Updated Go toolchain from 1.25 to 1.26.
  • Updated Atmos installer version from 1.206.0 to 1.208.0.
  • Updated AWS SDK and other key dependencies to latest stable versions.

• Documentation

  • Added comprehensive documentation and blog post for the new AWS Organization ID function, including usage examples and prerequisites.

what

• Added "Ansible" to the animated list of tools in the hero section and updated the visually hidden text for accessibility to include Ansible.
• Updated the footer message to mention Ansible alongside Terraform/OpenTofu and Packer, making it clear that teams can use these tools with Atmos.

why

• This pull request updates the website's homepage to highlight support for Ansible in addition to existing tools. The changes ensure Ansible is included in both the animated tool list and the page's accessibility text, as well as in the footer messaging.

Summary by CodeRabbit

• New Features

  • Added Ansible to the homepage's rotating featured technologies.
  • Updated homepage promotional copy to mention Ansible alongside Terraform/OpenTofu and Packer.

• Accessibility

  • Updated visually-hidden/screen-reader text to include Ansible in the spoken description of the rotating showcase.

what

• This pull request introduces a comprehensive demo example, documentation updates, and test cases. The changes expand the Atmos component model to include Ansible alongside Terraform, Helmfile, and Packer, and provide users with clear guidance and examples for configuring, running, and testing Ansible playbooks through Atmos.

• Added a complete demo-ansible example, including stack manifests, catalog defaults, Ansible playbook, inventory, Atmos configuration, and .gitignore entries for Ansible artifacts. This demonstrates variable handling, catalog pattern, and per-environment overrides for Ansible components. [1] [2] [3] [4] [[5]](diffhunk://#dif...