feat: Add source provisioning example

[osterman]

what

• Added examples/source-provisioning/ demonstrating the source provisioner feature for Just-in-Time component vendoring
• Includes separate dev and prod stacks using different module versions
• Demonstrates workdir isolation for terraform execution
• Simple, focused example showing one feature without catalog complexity

why

• Provides a working reference for users learning source provisioning
• Complements existing test fixtures and documentation with a clean runnable example
• Enables quick validation that source provisioning works end-to-end

references

• Source Provisioner PRD
• Provisioner System

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added source provisioning example with comprehensive README documentation and configuration samples demonstrating just-in-time component vendoring across development and production environments.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a source provisioning example directory with Atmos configuration files and documentation demonstrating inline JIT component vendoring. The example includes deployment manifests for dev and prod stages that reference an external Terraform module.

Changes

Cohort / File(s)	Summary
Documentation & Setup .gitignore, README.md	Adds .gitignore entries for vendored source directories and comprehensive README documenting the source provisioning workflow with CLI usage steps and configuration examples.
Atmos Configuration atmos.yaml	Defines root configuration mapping Terraform components to their base path and setting up stacks with stage-based naming template.
Deployment Manifests stacks/deploy/dev.yaml, stacks/deploy/prod.yaml	Declares myapp Terraform component sourced from terraform-null-label (different refs: 0.25.0 for dev, 0.24.1 for prod) with workdir provisioning enabled and environment-specific variables.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

no-release

Suggested reviewers

• aknysh

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding a new source provisioning example to the examples directory.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch osterman/source-provision-example

---

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between fd590f4 and 5743884.

📒 Files selected for processing (5)

• examples/source-provisioning/.gitignore
• examples/source-provisioning/README.md
• examples/source-provisioning/atmos.yaml
• examples/source-provisioning/stacks/deploy/dev.yaml
• examples/source-provisioning/stacks/deploy/prod.yaml

🧰 Additional context used

🧠 Learnings (12)

📓 Common learnings

Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.

Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:206-206
Timestamp: 2025-01-17T00:18:57.769Z
Learning: For indirect dependencies with license compliance issues in the cloudposse/atmos repository, the team prefers to handle them in follow-up PRs rather than blocking the current changes, as these issues often require deeper investigation of the dependency tree.

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: toolchain/http_client_test.go:3-10
Timestamp: 2025-09-10T21:17:55.273Z
Learning: In the cloudposse/atmos repository, imports should never be changed as per samtholiya's coding guidelines.

Learnt from: osterman
Repo: cloudposse/atmos PR: 899
File: examples/tests/test-vendor/test-components/main.tf:1-7
Timestamp: 2025-01-08T19:01:32.938Z
Learning: In the examples/tests directory of the atmos project, code examples are intentionally kept minimal and simple to facilitate understanding. Avoid suggesting additional complexity or validations that might make the examples harder to follow.

Learnt from: osterman
Repo: cloudposse/atmos PR: 1907
File: demos/fixtures/acme/stacks/catalog/api.yaml:1-29
Timestamp: 2026-01-09T04:49:35.038Z
Learning: In the cloudposse/atmos demos/fixtures, components can provide Terraform outputs via `remote_state_backend.static` configuration blocks instead of traditional Terraform output blocks. This pattern is used for demo/fixture purposes to simulate cross-component state references without deploying actual infrastructure. The `!terraform.state` YAML function reads from these static backends.

Learnt from: RoseSecurity
Repo: cloudposse/atmos PR: 797
File: pkg/list/atmos.yaml:213-214
Timestamp: 2024-11-25T17:17:15.703Z
Learning: The file `pkg/list/atmos.yaml` is primarily intended for testing purposes.

Learnt from: osterman
Repo: cloudposse/atmos PR: 1686
File: docs/prd/tool-dependencies-integration.md:58-64
Timestamp: 2025-12-13T06:07:37.766Z
Learning: cloudposse/atmos: For PRD docs (docs/prd/*.md), markdownlint issues like MD040/MD010/MD034 can be handled in a separate documentation cleanup commit and should not block the current PR.

📚 Learning: 2026-01-09T04:49:35.038Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1907
File: demos/fixtures/acme/stacks/catalog/api.yaml:1-29
Timestamp: 2026-01-09T04:49:35.038Z
Learning: In the cloudposse/atmos demos/fixtures, components can provide Terraform outputs via `remote_state_backend.static` configuration blocks instead of traditional Terraform output blocks. This pattern is used for demo/fixture purposes to simulate cross-component state references without deploying actual infrastructure. The `!terraform.state` YAML function reads from these static backends.

Applied to files:

• examples/source-provisioning/stacks/deploy/prod.yaml
• examples/source-provisioning/atmos.yaml
• examples/source-provisioning/README.md
• examples/source-provisioning/stacks/deploy/dev.yaml

📚 Learning: 2024-12-01T00:33:20.298Z

Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: examples/tests/stacks/catalog/terraform/template-functions-test2/defaults.yaml:28-32
Timestamp: 2024-12-01T00:33:20.298Z
Learning: In `examples/tests/stacks/catalog/terraform/template-functions-test2/defaults.yaml`, `!exec atmos terraform output` is used in examples to demonstrate its usage, even though `!terraform.output` is the recommended approach according to the documentation.

Applied to files:

• examples/source-provisioning/stacks/deploy/prod.yaml
• examples/source-provisioning/atmos.yaml
• examples/source-provisioning/README.md
• examples/source-provisioning/stacks/deploy/dev.yaml

📚 Learning: 2025-12-24T04:29:23.938Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1891
File: pkg/ci/terraform/templates/apply.md:17-17
Timestamp: 2025-12-24T04:29:23.938Z
Learning: In the cloudposse/atmos repository, Terraform CI templates (pkg/ci/terraform/templates/*.md) are rendered using TerraformTemplateContext (defined in pkg/ci/terraform/context.go), not the base ci.TemplateContext. TerraformTemplateContext provides top-level fields: .Resources (ci.ResourceCounts), .HasChanges() method, and .HasDestroy field, which are correctly accessed directly in templates without a .Result prefix.

Applied to files:

• examples/source-provisioning/stacks/deploy/prod.yaml
• examples/source-provisioning/atmos.yaml
• examples/source-provisioning/README.md
• examples/source-provisioning/stacks/deploy/dev.yaml

📚 Learning: 2024-11-25T17:17:15.703Z

Learnt from: RoseSecurity
Repo: cloudposse/atmos PR: 797
File: pkg/list/atmos.yaml:213-214
Timestamp: 2024-11-25T17:17:15.703Z
Learning: The file `pkg/list/atmos.yaml` is primarily intended for testing purposes.

Applied to files:

• examples/source-provisioning/atmos.yaml

📚 Learning: 2024-12-12T15:17:45.245Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 808
File: examples/demo-atmos.d/atmos.d/tools/helmfile.yml:10-10
Timestamp: 2024-12-12T15:17:45.245Z
Learning: In `examples/demo-atmos.d/atmos.d/tools/helmfile.yml`, when suggesting changes to `kubeconfig_path`, ensure that the values use valid Go template syntax.

Applied to files:

• examples/source-provisioning/atmos.yaml

📚 Learning: 2025-09-10T21:17:55.273Z

Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1466
File: toolchain/http_client_test.go:3-10
Timestamp: 2025-09-10T21:17:55.273Z
Learning: In the cloudposse/atmos repository, imports should never be changed as per samtholiya's coding guidelines.

Applied to files:

• examples/source-provisioning/atmos.yaml
• examples/source-provisioning/stacks/deploy/dev.yaml

📚 Learning: 2025-01-25T03:51:57.689Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 934
File: tests/fixtures/scenarios/docs-generate/README.md.gotmpl:99-118
Timestamp: 2025-01-25T03:51:57.689Z
Learning: For the cloudposse/atmos repository, changes to template contents should be handled in dedicated PRs and are typically considered out of scope for PRs focused on other objectives.

Applied to files:

• examples/source-provisioning/atmos.yaml
• examples/source-provisioning/stacks/deploy/dev.yaml

📚 Learning: 2025-01-25T15:21:40.413Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 808
File: examples/demo-atmos-cli-imports/atmos.yaml:8-8
Timestamp: 2025-01-25T15:21:40.413Z
Learning: In Atmos, when a directory is specified for configuration loading (e.g., in the `import` section of atmos.yaml), all files within that directory should be treated as Atmos configurations. Do not suggest restricting file extensions in directory-based glob patterns.

Applied to files:

• examples/source-provisioning/atmos.yaml

📚 Learning: 2025-03-18T12:26:25.329Z

Learnt from: Listener430
Repo: cloudposse/atmos PR: 1149
File: tests/snapshots/TestCLICommands_atmos_vendor_pull_ssh.stderr.golden:7-7
Timestamp: 2025-03-18T12:26:25.329Z
Learning: In the Atmos project, typos or inconsistencies in test snapshot files (such as "terrafrom" instead of "terraform") may be intentional as they capture the exact output of commands and should not be flagged as issues requiring correction.

Applied to files:

• examples/source-provisioning/atmos.yaml

📚 Learning: 2025-12-13T03:21:35.786Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 1813
File: cmd/terraform/shell.go:28-73
Timestamp: 2025-12-13T03:21:35.786Z
Learning: In Atmos, when calling cfg.InitCliConfig, you must first populate the schema.ConfigAndStacksInfo struct with global flag values using flags.ParseGlobalFlags(cmd, v) rather than passing an empty struct. The LoadConfig function (pkg/config/load.go) reads config selection fields (AtmosConfigFilesFromArg, AtmosConfigDirsFromArg, BasePath, ProfilesFromArg) directly from the ConfigAndStacksInfo struct, NOT from Viper. Passing an empty struct causes config selection flags (--base-path, --config, --config-path, --profile) to be silently ignored. Correct pattern: parse flags → populate struct → call InitCliConfig. See cmd/terraform/plan_diff.go for reference implementation.

Applied to files:

• examples/source-provisioning/atmos.yaml

📚 Learning: 2024-10-31T01:22:09.586Z

Learnt from: osterman
Repo: cloudposse/atmos PR: 737
File: examples/demo-vendoring/vendor.d/vendor1.yaml:10-11
Timestamp: 2024-10-31T01:22:09.586Z
Learning: In `examples/demo-vendoring/vendor.d/vendor1.yaml`, when specifying the source for the `ipinfo` component, it's acceptable to use `main` as the version reference if pinning to a specific version is not practical.

Applied to files:

• examples/source-provisioning/README.md

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Lint (golangci)
• GitHub Check: Acceptance Tests (macos)
• GitHub Check: Acceptance Tests (windows)
• GitHub Check: Acceptance Tests (linux)
• GitHub Check: Summary

🔇 Additional comments (5)

examples/source-provisioning/stacks/deploy/dev.yaml (1)

1-17: Clean and focused example.

The manifest structure is correct. Good use of a pinned version reference and the workdir provisioning setup aligns with the example's purpose.

examples/source-provisioning/stacks/deploy/prod.yaml (1)

1-16: Solid prod counterpart.

Using a different module version (0.24.1 vs dev's 0.25.0) effectively demonstrates the multi-version capability. Structure is consistent with dev.yaml.

examples/source-provisioning/atmos.yaml (1)

1-11: Well-structured Atmos config.

The paths and name_template align correctly with the stack manifests. Minimal config that gets the job done.

examples/source-provisioning/.gitignore (1)

1-3: Correct ignores for vendored content.

Keeps the example clean by excluding generated directories.

examples/source-provisioning/README.md (1)

1-41: Clear documentation.

The usage steps and configuration snippet provide a straightforward walkthrough. Cleanup instructions align with the .gitignore entries.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.32%. Comparing base (8d217c6) to head (17e3e51).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1962      +/-   ##
==========================================
- Coverage   74.34%   74.32%   -0.03%     
==========================================
  Files         774      774              
  Lines       70117    70117              
==========================================
- Hits        52129    52112      -17     
- Misses      14567    14583      +16     
- Partials     3421     3422       +1     

Flag	Coverage Δ
unittests	74.32% <ø> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.