Update Atmos YAML functions docs #1826
Conversation
aknysh
added
the
no-release
|
💥 This pull request now has conflicts. Could you fix it @aknysh? 🙏 |
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
📝 WalkthroughWalkthroughDocumentation updates add "Type-Aware Merging" notes across multiple YAML function pages, introduce a new reference page for YAML function merging, expand quoting/escaping guidance and examples for terraform-related YAML functions, and lightly reformat the functions index migration table. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (1)website/**📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
Files:
🧠 Learnings (9)📓 Common learnings📚 Learning: 2024-12-03T04:01:16.446ZApplied to files:
📚 Learning: 2025-01-19T22:30:27.600ZApplied to files:
📚 Learning: 2024-12-01T00:33:20.298ZApplied to files:
📚 Learning: 2025-01-19T22:30:27.600ZApplied to files:
📚 Learning: 2025-04-03T10:57:04.602ZApplied to files:
📚 Learning: 2025-09-27T20:50:20.564ZApplied to files:
📚 Learning: 2025-03-17T18:41:08.831ZApplied to files:
📚 Learning: 2024-12-03T05:18:49.169ZApplied to files:
🪛 LanguageToolwebsite/docs/reference/yaml-function-merging.mdx[typographical] ~34-~34: Consider using a typographic close quote here. (EN_QUOTES) [typographical] ~50-~50: To join two clauses or introduce examples, consider using an em dash. (DASH_RULE) ⏰ 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). (3)
🔇 Additional comments (1)
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. Comment |
|
@coderabbitai full review please |
|
@aknysh: I'll perform a full review of the documentation changes in this PR. 🧠 Learnings used✅ Actions performedFull review triggered. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1826 +/- ##
=======================================
Coverage 72.16% 72.16%
=======================================
Files 475 475
Lines 45713 45713
=======================================
+ Hits 32988 32990 +2
+ Misses 10104 10103 -1
+ Partials 2621 2620 -1
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
📝 WalkthroughWalkthroughA dependency version bump for github.com/aws/smithy-go from v1.23.2 to v1.24.0 with corresponding license URL updates, plus documentation additions explaining deferred evaluation of YAML functions during configuration merging across multiple function reference docs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 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.
⛔ Files ignored due to path filters (1)
go.sumis excluded by!**/*.sum
📒 Files selected for processing (10)
NOTICE(2 hunks)go.mod(1 hunks)website/docs/functions/index.mdx(1 hunks)website/docs/functions/yaml/env.mdx(1 hunks)website/docs/functions/yaml/exec.mdx(1 hunks)website/docs/functions/yaml/store.get.mdx(1 hunks)website/docs/functions/yaml/store.mdx(1 hunks)website/docs/functions/yaml/template.mdx(1 hunks)website/docs/functions/yaml/terraform.output.mdx(2 hunks)website/docs/functions/yaml/terraform.state.mdx(3 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in thewebsite/directory when adding new features, ensure consistency between CLI help text and website documentation, and follow the website's documentation structure and style
Keep website code in thewebsite/directory, follow the existing website architecture and style, and test website changes locally before committing
Keep CLI documentation and website documentation in sync and document new features on the website with examples and use cases
Files:
website/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/store.mdx
{go.mod,go.sum}
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
Files:
go.mod
🧠 Learnings (21)
📓 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: 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.
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: Go version 1.23.0 was deliberately introduced by the maintainer (aknysh) in January 2025. While this might be a pre-release or development version of Go, it has been approved for use in this project.
📚 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:
website/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/store.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
Applied to files:
website/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/store.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!include` allows downloading local or remote files from different sources and assigning their contents to sections in stack manifests. It supports various protocols (file, http, git, s3, etc.) and can filter content using YQ expressions.
Applied to files:
website/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/store.mdx
📚 Learning: 2024-12-03T04:01:16.446Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:0-0
Timestamp: 2024-12-03T04:01:16.446Z
Learning: In the `terraform.output.mdx` documentation file (`website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx`), the cache invalidation and cache scope behavior for the `!terraform.output` function are already described.
Applied to files:
website/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-30T19:03:50.738Z
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Applied to files:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/store.mdx
📚 Learning: 2024-12-03T03:49:30.395Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:104-110
Timestamp: 2024-12-03T03:49:30.395Z
Learning: In the documentation for `!terraform.output`, warnings about template variable availability are already covered in other sections, so no need to suggest adding them here.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2024-12-03T05:18:49.169Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:40-213
Timestamp: 2024-12-03T05:18:49.169Z
Learning: In the context of the Atmos project, it's acceptable for functions like `execTerraformOutput` to remain as single functions if they perform a single purpose, such as retrieving Terraform outputs for a component in a stack, even if the function is lengthy.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-27T20:50:20.564Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to internal/exec/template_funcs.go : New configs support Go templating with FuncMap() from internal/exec/template_funcs.go. Implement template functions in internal/exec/template_funcs.go, register them, add tests, and update documentation.
Applied to files:
website/docs/functions/index.mdx
📚 Learning: 2025-02-09T18:43:53.902Z
Learnt from: haitham911
Repo: cloudposse/atmos PR: 808
File: pkg/config/loader.go:141-145
Timestamp: 2025-02-09T18:43:53.902Z
Learning: In the Atmos configuration loading process, errors during individual config file loading/merging should be logged but not propagate up to break the entire process. This design choice enables resilient partial configuration loading.
Applied to files:
website/docs/functions/yaml/env.mdx
📚 Learning: 2025-11-24T17:35:37.209Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to {go.mod,go.sum} : Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
Applied to files:
go.mod
📚 Learning: 2025-01-17T00:21:32.987Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: Go version 1.23.0 was deliberately introduced by the maintainer (aknysh) in January 2025. While this might be a pre-release or development version of Go, it has been approved for use in this project.
Applied to files:
go.mod
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
go.modNOTICE
📚 Learning: 2025-01-17T00:21:32.987Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: The project uses Go version 1.23.0 which has been confirmed by the maintainer to be working in production for months. Do not flag this as an invalid Go version.
Applied to files:
go.mod
📚 Learning: 2025-11-01T20:24:29.557Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1714
File: NOTICE:0-0
Timestamp: 2025-11-01T20:24:29.557Z
Learning: In the cloudposse/atmos repository, the NOTICE file is programmatically generated and should not be manually edited. Issues with dependency license URLs in NOTICE will be resolved when upstream package metadata is corrected.
Applied to files:
NOTICE
📚 Learning: 2025-01-17T00:18:57.769Z
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.
Applied to files:
NOTICE
📚 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:
NOTICE
📚 Learning: 2025-05-30T03:21:37.197Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1274
File: go.mod:63-63
Timestamp: 2025-05-30T03:21:37.197Z
Learning: The redis dependency (github.com/redis/go-redis/v9) in the atmos project is only used in tests, not in production code.
Applied to files:
NOTICE
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to **/*.go : Organize imports in three groups separated by blank lines (Go stdlib, 3rd-party excluding cloudposse/atmos, Atmos packages), sorted alphabetically. Maintain aliases: cfg, log, u, errUtils.
Applied to files:
NOTICE
📚 Learning: 2025-01-19T23:13:50.429Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 943
File: internal/exec/describe_config.go:37-37
Timestamp: 2025-01-19T23:13:50.429Z
Learning: When reviewing pointer usage with `EvaluateYqExpression`, check if the `atmosConfig` parameter is already a pointer (e.g., when returned by `InitCliConfig`) to avoid suggesting unnecessary address-of operations.
Applied to files:
website/docs/functions/yaml/store.mdx
🪛 GitHub Actions: Dependency Review
NOTICE
[error] 1-1: NOTICE file is out of date. Run './scripts/generate-notice.sh' locally and commit the changes.
🪛 Gitleaks (8.29.1)
website/docs/functions/yaml/store.get.mdx
[high] 95-95: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
website/docs/functions/yaml/template.mdx
[typographical] ~166-~166: Consider using a typographic opening quote here.
Context: ...o, Atmos would attempt to merge a list (["sg-111", "sg-222"]) with a YAML functio...
(EN_QUOTES)
website/docs/functions/yaml/store.get.mdx
[typographical] ~105-~105: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("default-key-12345") with a YAML functio...
(EN_QUOTES)
website/docs/functions/yaml/terraform.output.mdx
[typographical] ~81-~81: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
website/docs/functions/yaml/exec.mdx
[typographical] ~95-~95: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("1.0.0") with a YAML function reference ...
(EN_QUOTES)
[style] ~99-~99: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 3573 characters long)
Context: ...aluation** of YAML functions (including !exec, !terraform.output, !terraform.state, !template, !store, !store.get, and !env) until after all configuration laye...
(EN_EXCESSIVE_EXCLAMATION)
website/docs/functions/yaml/env.mdx
[typographical] ~107-~107: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("postgresql://localhost:5432/mydb") with...
(EN_QUOTES)
[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ...ates type conflicts: 1. Defer Phase - YAML functions are identified and tempor...
(DASH_RULE)
[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...ced with placeholders 2. Merge Phase - All configuration layers merge without t...
(DASH_RULE)
[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...out type conflicts 3. Evaluate Phase - YAML functions are evaluated and applied...
(DASH_RULE)
[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...s - Flexible Configuration Patterns - Mix static values and YAML functions acr...
(DASH_RULE)
[typographical] ~122-~122: To join two clauses or introduce examples, consider using an em dash.
Context: ...ithout conflicts - Gradual Migration - Migrate from static to dynamic configura...
(DASH_RULE)
[typographical] ~123-~123: To join two clauses or introduce examples, consider using an em dash.
Context: ...s incrementally - Team Collaboration - Different teams can use different approa...
(DASH_RULE)
[typographical] ~124-~124: To join two clauses or introduce examples, consider using an em dash.
Context: ...r layers - Multi-Environment Support - Use static values in dev/staging and YAM...
(DASH_RULE)
website/docs/functions/yaml/terraform.state.mdx
[typographical] ~94-~94: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
[typographical] ~174-~174: Consider using a typographic opening quote here.
Context: ...must wrap the key in double quotes like ["github-dependabot"]. This often clashes...
(EN_QUOTES)
[style] ~562-~562: Using many exclamation marks might seem excessive (in this case: 39 exclamation marks for a text that’s 15231 characters long)
Context: ...onent has not yet been provisioned, the !terraform.state function will return `n...
(EN_EXCESSIVE_EXCLAMATION)
website/docs/functions/yaml/store.mdx
[typographical] ~100-~100: Consider using a typographic opening quote here.
Context: ...o, Atmos would attempt to merge a list (["subnet-111", "subnet-222"]) with a YAML...
(EN_QUOTES)
⏰ 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). (1)
- GitHub Check: Summary
🔇 Additional comments (16)
go.mod (1)
33-33: LGTM!Dependency update for smithy-go looks good. Version bump aligns with the NOTICE file changes.
website/docs/functions/index.mdx (1)
95-99: LGTM!Table reformatting improves readability. Content remains unchanged.
website/docs/functions/yaml/store.mdx (1)
76-118: LGTM!Documentation for deferred evaluation is clear and well-structured. The three-phase approach explanation and benefits are helpful for users understanding the merge behavior.
website/docs/functions/yaml/template.mdx (1)
142-184: LGTM!Deferred evaluation documentation is consistent with other YAML functions. The template-specific example is appropriate and clear.
website/docs/functions/yaml/env.mdx (1)
83-125: LGTM!Deferred evaluation documentation is clear and consistent. The environment variable example fits well with the
!envfunction's purpose.website/docs/functions/yaml/exec.mdx (1)
71-112: LGTM!Deferred evaluation section is well-structured. The build_number example is a good fit for the
!execfunction use case.website/docs/functions/yaml/store.get.mdx (1)
81-123: LGTM!Deferred evaluation documentation is consistent and clear. The external API key example is appropriate for the
!store.getfunction's use case.NOTICE (1)
186-186: Run./scripts/generate-notice.shto regenerate the NOTICE file.The pipeline failure indicates the NOTICE file is out of date. This file is programmatically generated and must be updated by running the generation script, not by manual edits. Execute
./scripts/generate-notice.shto ensure all dependency license information is current.website/docs/functions/yaml/terraform.output.mdx (3)
57-98: Deferred Evaluation section is well-structured and clear.The new documentation effectively explains the three-phase approach (Defer, Merge, Evaluate) with a concrete problem/solution example. The concrete YAML examples showing type conflicts are helpful for understanding the feature. Benefits section clearly articulates use cases.
194-196: Escaped single-quote example adds practical value.The new example demonstrating
''escaping for single quotes within YQ expressions (app''s-name) complements the quote handling guidance and provides users with a concrete reference implementation.
81-81: Minor typographical issue with backtick quotes.LanguageTool suggests using typographic close quotes instead of backticks in the string reference. While backticks are commonly used in technical documentation for code snippets, consider aligning with the site's style guidelines.
This is a style preference and can be addressed separately if the site standardizes on typographic quotes for string literals.
⛔ Skipped due to learnings
Learnt from: samtholiya Repo: cloudposse/atmos PR: 1068 File: tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden:59-64 Timestamp: 2025-02-18T13:13:11.497Z Learning: For Atmos CLI help text, angle brackets in command examples and flag descriptions should be escaped using HTML entities (e.g., `<component>`) rather than converted to backticks or other markdown formatting.Learnt from: samtholiya Repo: cloudposse/atmos PR: 1068 File: tests/snapshots/TestCLICommands_atmos_terraform_apply_--help.stdout.golden:0-0 Timestamp: 2025-02-19T05:50:35.853Z Learning: Backtick formatting should only be applied to flag descriptions in Go source files, not in golden test files (test snapshots) as they are meant to capture the raw command output.Learnt from: osterman Repo: cloudposse/atmos PR: 1505 File: website/docs/cli/commands/completion.mdx:124-127 Timestamp: 2025-09-24T22:20:39.209Z Learning: In Docusaurus (specifically the cloudposse/atmos repository), backticks render correctly as code formatting even when used inside HTML elements like <dl>/<dt>/<dd> tags in MDX files. No need to replace with <code> tags.Learnt from: haitham911 Repo: cloudposse/atmos PR: 1085 File: pkg/config/imports.go:68-75 Timestamp: 2025-03-17T18:41:08.831Z Learning: In the Atmos configuration import system, errors during config file merging are logged at debug level and the process continues with other imports rather than failing completely, prioritizing resilience over strict correctness.Learnt from: haitham911 Repo: cloudposse/atmos PR: 1091 File: pkg/config/load_config_args.go:61-82 Timestamp: 2025-04-03T10:57:04.602Z Learning: In the Atmos configuration system, errors in `mergeDefaultImports` and `mergeImports` functions are intentionally only logged as debug messages without returning errors, as they are considered non-critical. Only errors in critical functions like `mergeConfigFile` are returned to halt execution.Learnt from: haitham911 Repo: cloudposse/atmos PR: 808 File: pkg/config/loader.go:141-145 Timestamp: 2025-02-09T18:43:53.902Z Learning: In the Atmos configuration loading process, errors during individual config file loading/merging should be logged but not propagate up to break the entire process. This design choice enables resilient partial configuration loading.Learnt from: Cerebrovinny Repo: cloudposse/atmos PR: 1560 File: pkg/utils/string_utils.go:43-64 Timestamp: 2025-09-30T19:03:50.738Z Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.Learnt from: aknysh Repo: cloudposse/atmos PR: 0 File: :0-0 Timestamp: 2025-01-19T22:30:27.600Z Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).website/docs/functions/yaml/terraform.state.mdx (5)
70-112: Deferred Evaluation section mirrors terraform.output with appropriate context.The section properly adapts the three-phase approach to
!terraform.state, maintaining structural consistency with the parallel terraform.output documentation while correctly referencing terraform.state in examples.
174-207: Quote handling section is comprehensive and well-organized.The extended examples (lines 180, 187, 190, 196) consistently use the
.outputsprefix appropriate to terraform.state, demonstrating key scenarios (special characters, nested maps, templating, escaped quotes). The escaping rules section is clear. The tip cross-referencing terraform.output and !include maintains awareness of shared patterns.
562-563: Cold-start consideration enhancement is helpful.The updated Considerations section (now clarifying that
!terraform.statereturnsnullif components aren't provisioned, with a cross-link to the default values section) provides practical guidance for users and improves the discoverability of related techniques.
57-207: Documentation achieves PR objectives: self-contained, parallel structure, and consistency.Both files now present equivalent deferred evaluation explanations with function-specific examples, eliminating cross-page dependencies. Quote handling guidance is complete in each file with concrete examples. The escaped single-quote patterns (
app''s-name) are consistent between functions. This aligns well with the stated goals of PR #1821 and #1560.Also applies to: 70-207
94-94: Minor typographical issue with backtick quotes (matching terraform.output).LanguageTool flags the backtick string reference (
"10.0.0.0/16") as needing typographic quotes. Consistent with the similar note in terraform.output—can be addressed as a site-wide style update.⛔ Skipped due to learnings
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.Learnt from: samtholiya Repo: cloudposse/atmos PR: 1068 File: tests/snapshots/TestCLICommands_atmos_terraform_apply_--help.stdout.golden:0-0 Timestamp: 2025-02-19T05:50:35.853Z Learning: Backtick formatting should only be applied to flag descriptions in Go source files, not in golden test files (test snapshots) as they are meant to capture the raw command output.Learnt from: haitham911 Repo: cloudposse/atmos PR: 1085 File: pkg/config/imports.go:68-75 Timestamp: 2025-03-17T18:41:08.831Z Learning: In the Atmos configuration import system, errors during config file merging are logged at debug level and the process continues with other imports rather than failing completely, prioritizing resilience over strict correctness.Learnt from: haitham911 Repo: cloudposse/atmos PR: 1091 File: pkg/config/load_config_args.go:61-82 Timestamp: 2025-04-03T10:57:04.602Z Learning: In the Atmos configuration system, errors in `mergeDefaultImports` and `mergeImports` functions are intentionally only logged as debug messages without returning errors, as they are considered non-critical. Only errors in critical functions like `mergeConfigFile` are returned to halt execution.Learnt from: haitham911 Repo: cloudposse/atmos PR: 808 File: pkg/config/loader.go:141-145 Timestamp: 2025-02-09T18:43:53.902Z Learning: In the Atmos configuration loading process, errors during individual config file loading/merging should be logged but not propagate up to break the entire process. This design choice enables resilient partial configuration loading.Learnt from: Cerebrovinny Repo: cloudposse/atmos PR: 1560 File: pkg/utils/string_utils.go:43-64 Timestamp: 2025-09-30T19:03:50.738Z Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.Learnt from: aknysh Repo: cloudposse/atmos PR: 0 File: :0-0 Timestamp: 2025-01-19T22:30:27.600Z Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
There was a problem hiding this comment.
Actionable comments posted: 2
📜 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.
⛔ Files ignored due to path filters (1)
go.sumis excluded by!**/*.sum
📒 Files selected for processing (10)
NOTICE(2 hunks)go.mod(1 hunks)website/docs/functions/index.mdx(1 hunks)website/docs/functions/yaml/env.mdx(1 hunks)website/docs/functions/yaml/exec.mdx(1 hunks)website/docs/functions/yaml/store.get.mdx(1 hunks)website/docs/functions/yaml/store.mdx(1 hunks)website/docs/functions/yaml/template.mdx(1 hunks)website/docs/functions/yaml/terraform.output.mdx(2 hunks)website/docs/functions/yaml/terraform.state.mdx(3 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in thewebsite/directory when adding new features, ensure consistency between CLI help text and website documentation, and follow the website's documentation structure and style
Keep website code in thewebsite/directory, follow the existing website architecture and style, and test website changes locally before committing
Keep CLI documentation and website documentation in sync and document new features on the website with examples and use cases
Files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdx
{go.mod,go.sum}
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
Files:
go.mod
🧠 Learnings (22)
📓 Common learnings
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.
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: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to {go.mod,go.sum} : Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
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: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
📚 Learning: 2024-12-03T04:01:16.446Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:0-0
Timestamp: 2024-12-03T04:01:16.446Z
Learning: In the `terraform.output.mdx` documentation file (`website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx`), the cache invalidation and cache scope behavior for the `!terraform.output` function are already described.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/store.get.mdx
📚 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:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!include` allows downloading local or remote files from different sources and assigning their contents to sections in stack manifests. It supports various protocols (file, http, git, s3, etc.) and can filter content using YQ expressions.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdx
📚 Learning: 2024-12-03T05:18:49.169Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:40-213
Timestamp: 2024-12-03T05:18:49.169Z
Learning: In the context of the Atmos project, it's acceptable for functions like `execTerraformOutput` to remain as single functions if they perform a single purpose, such as retrieving Terraform outputs for a component in a stack, even if the function is lengthy.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2025-09-27T20:50:20.564Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/env.mdx
📚 Learning: 2025-09-30T19:03:50.738Z
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Applied to files:
website/docs/functions/yaml/store.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/store.get.mdx
📚 Learning: 2025-01-19T23:13:50.429Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 943
File: internal/exec/describe_config.go:37-37
Timestamp: 2025-01-19T23:13:50.429Z
Learning: When reviewing pointer usage with `EvaluateYqExpression`, check if the `atmosConfig` parameter is already a pointer (e.g., when returned by `InitCliConfig`) to avoid suggesting unnecessary address-of operations.
Applied to files:
website/docs/functions/yaml/store.mdx
📚 Learning: 2024-12-03T03:49:30.395Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:104-110
Timestamp: 2024-12-03T03:49:30.395Z
Learning: In the documentation for `!terraform.output`, warnings about template variable availability are already covered in other sections, so no need to suggest adding them here.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2025-11-24T17:35:37.209Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to {go.mod,go.sum} : Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
Applied to files:
NOTICEgo.mod
📚 Learning: 2025-01-17T00:21:32.987Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: Go version 1.23.0 was deliberately introduced by the maintainer (aknysh) in January 2025. While this might be a pre-release or development version of Go, it has been approved for use in this project.
Applied to files:
NOTICEgo.mod
📚 Learning: 2025-11-01T20:24:29.557Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1714
File: NOTICE:0-0
Timestamp: 2025-11-01T20:24:29.557Z
Learning: In the cloudposse/atmos repository, the NOTICE file is programmatically generated and should not be manually edited. Issues with dependency license URLs in NOTICE will be resolved when upstream package metadata is corrected.
Applied to files:
NOTICE
📚 Learning: 2025-01-17T00:18:57.769Z
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.
Applied to files:
NOTICE
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
NOTICEgo.mod
📚 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:
NOTICE
📚 Learning: 2025-05-30T03:21:37.197Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1274
File: go.mod:63-63
Timestamp: 2025-05-30T03:21:37.197Z
Learning: The redis dependency (github.com/redis/go-redis/v9) in the atmos project is only used in tests, not in production code.
Applied to files:
NOTICE
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to **/*.go : Organize imports in three groups separated by blank lines (Go stdlib, 3rd-party excluding cloudposse/atmos, Atmos packages), sorted alphabetically. Maintain aliases: cfg, log, u, errUtils.
Applied to files:
NOTICE
📚 Learning: 2025-06-23T02:14:30.937Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1327
File: cmd/terraform.go:111-117
Timestamp: 2025-06-23T02:14:30.937Z
Learning: In cmd/terraform.go, flags for the DescribeAffected function are added dynamically at runtime when info.Affected is true. This is intentional to avoid exposing internal flags like "file", "format", "verbose", "include-spacelift-admin-stacks", "include-settings", and "upload" in the terraform command interface, while still providing them for the shared DescribeAffected function used by both `atmos describe affected` and `atmos terraform apply --affected`.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to internal/exec/template_funcs.go : New configs support Go templating with FuncMap() from internal/exec/template_funcs.go. Implement template functions in internal/exec/template_funcs.go, register them, add tests, and update documentation.
Applied to files:
website/docs/functions/index.mdx
📚 Learning: 2025-02-09T18:43:53.902Z
Learnt from: haitham911
Repo: cloudposse/atmos PR: 808
File: pkg/config/loader.go:141-145
Timestamp: 2025-02-09T18:43:53.902Z
Learning: In the Atmos configuration loading process, errors during individual config file loading/merging should be logged but not propagate up to break the entire process. This design choice enables resilient partial configuration loading.
Applied to files:
website/docs/functions/yaml/env.mdx
📚 Learning: 2025-01-17T00:21:32.987Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: The project uses Go version 1.23.0 which has been confirmed by the maintainer to be working in production for months. Do not flag this as an invalid Go version.
Applied to files:
go.mod
🪛 GitHub Actions: Dependency Review
NOTICE
[error] 1-1: NOTICE file is out of date. Run './scripts/generate-notice.sh' locally and commit the changes.
🪛 Gitleaks (8.29.1)
website/docs/functions/yaml/store.get.mdx
[high] 95-95: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
website/docs/functions/yaml/exec.mdx
[typographical] ~95-~95: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("1.0.0") with a YAML function reference ...
(EN_QUOTES)
[style] ~99-~99: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 3573 characters long)
Context: ...aluation** of YAML functions (including !exec, !terraform.output, !terraform.state, !template, !store, !store.get, and !env) until after all configuration laye...
(EN_EXCESSIVE_EXCLAMATION)
website/docs/functions/yaml/store.mdx
[typographical] ~100-~100: Consider using a typographic opening quote here.
Context: ...o, Atmos would attempt to merge a list (["subnet-111", "subnet-222"]) with a YAML...
(EN_QUOTES)
website/docs/functions/yaml/terraform.output.mdx
[typographical] ~81-~81: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
website/docs/functions/yaml/terraform.state.mdx
[typographical] ~94-~94: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
[typographical] ~174-~174: Consider using a typographic opening quote here.
Context: ...must wrap the key in double quotes like ["github-dependabot"]. This often clashes...
(EN_QUOTES)
[style] ~562-~562: Using many exclamation marks might seem excessive (in this case: 39 exclamation marks for a text that’s 15231 characters long)
Context: ...onent has not yet been provisioned, the !terraform.state function will return `n...
(EN_EXCESSIVE_EXCLAMATION)
website/docs/functions/yaml/template.mdx
[typographical] ~166-~166: Consider using a typographic opening quote here.
Context: ...o, Atmos would attempt to merge a list (["sg-111", "sg-222"]) with a YAML functio...
(EN_QUOTES)
website/docs/functions/yaml/env.mdx
[typographical] ~107-~107: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("postgresql://localhost:5432/mydb") with...
(EN_QUOTES)
website/docs/functions/yaml/store.get.mdx
[typographical] ~105-~105: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("default-key-12345") with a YAML functio...
(EN_QUOTES)
⏰ 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). (1)
- GitHub Check: Summary
🔇 Additional comments (11)
website/docs/functions/yaml/exec.mdx (1)
70-112: Clear documentation of deferred evaluation.The new section effectively explains the three-phase approach and provides concrete examples. The duplication across multiple YAML function docs ensures each page is self-contained, which is good for user experience.
website/docs/functions/index.mdx (1)
95-100: Table formatting improved.The column width adjustments make the migration path table more readable.
website/docs/functions/yaml/env.mdx (1)
83-125: Well-structured deferred evaluation documentation.The database URL example effectively demonstrates the type conflict scenario and how deferred evaluation resolves it.
website/docs/functions/yaml/template.mdx (1)
142-184: Consistent deferred evaluation documentation.The security group IDs example with list types is a good fit for the template function context.
website/docs/functions/yaml/terraform.output.mdx (2)
57-99: Deferred evaluation documented for terraform.output.The CIDR block example is appropriate for networking-related Terraform outputs.
194-196: Helpful escaped single-quotes example.The
app''s-nameexample demonstrates the doubling technique for escaping single quotes inside YQ expressions, addressing a common edge case.website/docs/functions/yaml/terraform.state.mdx (3)
70-112: Deferred evaluation documented for terraform.state.The section maintains consistency with the other YAML function docs while using networking examples appropriate for state access.
172-207: Comprehensive quote handling guidance.The expanded section with multiple bracket notation examples (service accounts, nested maps, stack templating, escaped quotes) provides excellent coverage of common scenarios. The cross-reference to other YAML functions reinforces the shared parsing behavior.
562-563: Improved cold-start guidance.The update clarifies that unprovisionioned components return
nulland points users to the default value section, improving discoverability of the solution.website/docs/functions/yaml/store.mdx (1)
76-118: Clear deferred evaluation documentation with solid pedagogical structure.The new section walks through the problem (type conflicts during merge) → solution (three-phase deferred evaluation) → benefits in a natural progression. The concrete YAML example effectively illustrates why deferred evaluation matters when inheritance chains mix static values and YAML functions.
website/docs/functions/yaml/store.get.mdx (1)
81-123: Parallel structure to!storedocs maintains consistency across YAML function guides.The example adapts naturally to
!store.getcontext (API keys vs. subnet IDs), reinforcing the concept while staying domain-appropriate. The list of affected functions aligns with the companion!storedocumentation and reflects the full scope of deferred evaluation support.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
website/docs/functions/yaml/terraform.state.mdx (1)
562-563: Consider softening "provisioned" language for clarity.The update correctly notes that
!terraform.statereturnsnullfor unprovisioned components, but the phrasing could be slightly more explicit. Currently: "if the dependent component has not yet been provisioned, the!terraform.statefunction will returnnull."Consider rewording to: "if the referenced component's state file doesn't exist (e.g., not yet provisioned),
!terraform.statereturnsnull" to make it clear this applies to missing state files, not just provisioning status.website/docs/functions/yaml/store.get.mdx (1)
124-140: YQ expressions section provides clear practical examples.The progression from simple field extraction to nested defaults is intuitive. Examples span diverse scenarios (JSON objects, arrays, defaults) without being overwhelming. However, these examples would benefit from brief explanatory comments in the YAML to clarify what each line retrieves (e.g.,
# Extract database host from app-config).If you'd like, I can add inline YAML comments to each example to improve clarity—let me know if that aligns with your documentation style.
📜 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.
⛔ Files ignored due to path filters (1)
go.sumis excluded by!**/*.sum
📒 Files selected for processing (10)
NOTICE(2 hunks)go.mod(1 hunks)website/docs/functions/index.mdx(1 hunks)website/docs/functions/yaml/env.mdx(1 hunks)website/docs/functions/yaml/exec.mdx(1 hunks)website/docs/functions/yaml/store.get.mdx(1 hunks)website/docs/functions/yaml/store.mdx(1 hunks)website/docs/functions/yaml/template.mdx(1 hunks)website/docs/functions/yaml/terraform.output.mdx(2 hunks)website/docs/functions/yaml/terraform.state.mdx(3 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in thewebsite/directory when adding new features, ensure consistency between CLI help text and website documentation, and follow the website's documentation structure and style
Keep website code in thewebsite/directory, follow the existing website architecture and style, and test website changes locally before committing
Keep CLI documentation and website documentation in sync and document new features on the website with examples and use cases
Files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/index.mdx
{go.mod,go.sum}
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
Files:
go.mod
🧠 Learnings (21)
📓 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: 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.
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
📚 Learning: 2024-12-03T04:01:16.446Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:0-0
Timestamp: 2024-12-03T04:01:16.446Z
Learning: In the `terraform.output.mdx` documentation file (`website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx`), the cache invalidation and cache scope behavior for the `!terraform.output` function are already described.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/index.mdx
📚 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:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!include` allows downloading local or remote files from different sources and assigning their contents to sections in stack manifests. It supports various protocols (file, http, git, s3, etc.) and can filter content using YQ expressions.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/store.mdx
📚 Learning: 2024-12-03T05:18:49.169Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:40-213
Timestamp: 2024-12-03T05:18:49.169Z
Learning: In the context of the Atmos project, it's acceptable for functions like `execTerraformOutput` to remain as single functions if they perform a single purpose, such as retrieving Terraform outputs for a component in a stack, even if the function is lengthy.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2025-09-27T20:50:20.564Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.
Applied to files:
website/docs/functions/yaml/exec.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdx
📚 Learning: 2025-02-09T18:43:53.902Z
Learnt from: haitham911
Repo: cloudposse/atmos PR: 808
File: pkg/config/loader.go:141-145
Timestamp: 2025-02-09T18:43:53.902Z
Learning: In the Atmos configuration loading process, errors during individual config file loading/merging should be logged but not propagate up to break the entire process. This design choice enables resilient partial configuration loading.
Applied to files:
website/docs/functions/yaml/env.mdx
📚 Learning: 2025-11-24T17:35:37.209Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: .cursor/rules/atmos-rules.mdc:0-0
Timestamp: 2025-11-24T17:35:37.209Z
Learning: Applies to {go.mod,go.sum} : Manage dependencies with Go modules and keep dependencies up to date while minimizing external dependencies
Applied to files:
go.mod
📚 Learning: 2025-01-17T00:21:32.987Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: Go version 1.23.0 was deliberately introduced by the maintainer (aknysh) in January 2025. While this might be a pre-release or development version of Go, it has been approved for use in this project.
Applied to files:
go.mod
📚 Learning: 2025-07-05T20:59:02.914Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1363
File: internal/exec/template_utils.go:18-18
Timestamp: 2025-07-05T20:59:02.914Z
Learning: In the Atmos project, gomplate v4 is imported with a blank import (`_ "github.com/hairyhenderson/gomplate/v4"`) alongside v3 imports to resolve AWS SDK version conflicts. V3 uses older AWS SDK versions that conflict with newer AWS modules used by Atmos. A full migration to v4 requires extensive refactoring due to API changes and should be handled in a separate PR.
Applied to files:
go.modNOTICE
📚 Learning: 2025-01-17T00:21:32.987Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 944
File: go.mod:3-3
Timestamp: 2025-01-17T00:21:32.987Z
Learning: The project uses Go version 1.23.0 which has been confirmed by the maintainer to be working in production for months. Do not flag this as an invalid Go version.
Applied to files:
go.mod
📚 Learning: 2025-11-01T20:24:29.557Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1714
File: NOTICE:0-0
Timestamp: 2025-11-01T20:24:29.557Z
Learning: In the cloudposse/atmos repository, the NOTICE file is programmatically generated and should not be manually edited. Issues with dependency license URLs in NOTICE will be resolved when upstream package metadata is corrected.
Applied to files:
NOTICE
📚 Learning: 2025-01-17T00:18:57.769Z
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.
Applied to files:
NOTICE
📚 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:
NOTICE
📚 Learning: 2025-05-30T03:21:37.197Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 1274
File: go.mod:63-63
Timestamp: 2025-05-30T03:21:37.197Z
Learning: The redis dependency (github.com/redis/go-redis/v9) in the atmos project is only used in tests, not in production code.
Applied to files:
NOTICE
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to **/*.go : Organize imports in three groups separated by blank lines (Go stdlib, 3rd-party excluding cloudposse/atmos, Atmos packages), sorted alphabetically. Maintain aliases: cfg, log, u, errUtils.
Applied to files:
NOTICE
📚 Learning: 2025-09-30T19:03:50.738Z
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Applied to files:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2024-12-03T03:49:30.395Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:104-110
Timestamp: 2024-12-03T03:49:30.395Z
Learning: In the documentation for `!terraform.output`, warnings about template variable availability are already covered in other sections, so no need to suggest adding them here.
Applied to files:
website/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdx
📚 Learning: 2025-01-19T23:13:50.429Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 943
File: internal/exec/describe_config.go:37-37
Timestamp: 2025-01-19T23:13:50.429Z
Learning: When reviewing pointer usage with `EvaluateYqExpression`, check if the `atmosConfig` parameter is already a pointer (e.g., when returned by `InitCliConfig`) to avoid suggesting unnecessary address-of operations.
Applied to files:
website/docs/functions/yaml/store.mdx
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to internal/exec/template_funcs.go : New configs support Go templating with FuncMap() from internal/exec/template_funcs.go. Implement template functions in internal/exec/template_funcs.go, register them, add tests, and update documentation.
Applied to files:
website/docs/functions/index.mdx
🪛 GitHub Actions: Dependency Review
NOTICE
[error] 1-1: NOTICE file is out of date. Run './scripts/generate-notice.sh' locally and commit the changes.
🪛 Gitleaks (8.29.1)
website/docs/functions/yaml/store.get.mdx
[high] 95-95: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
website/docs/functions/yaml/exec.mdx
[typographical] ~95-~95: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("1.0.0") with a YAML function reference ...
(EN_QUOTES)
[style] ~99-~99: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 3573 characters long)
Context: ...aluation** of YAML functions (including !exec, !terraform.output, !terraform.state, !template, !store, !store.get, and !env) until after all configuration laye...
(EN_EXCESSIVE_EXCLAMATION)
website/docs/functions/yaml/env.mdx
[typographical] ~107-~107: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("postgresql://localhost:5432/mydb") with...
(EN_QUOTES)
website/docs/functions/yaml/store.get.mdx
[typographical] ~105-~105: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("default-key-12345") with a YAML functio...
(EN_QUOTES)
website/docs/functions/yaml/template.mdx
[typographical] ~166-~166: Consider using a typographic opening quote here.
Context: ...o, Atmos would attempt to merge a list (["sg-111", "sg-222"]) with a YAML functio...
(EN_QUOTES)
website/docs/functions/yaml/terraform.state.mdx
[typographical] ~94-~94: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
[typographical] ~174-~174: Consider using a typographic opening quote here.
Context: ...must wrap the key in double quotes like ["github-dependabot"]. This often clashes...
(EN_QUOTES)
[style] ~562-~562: Using many exclamation marks might seem excessive (in this case: 39 exclamation marks for a text that’s 15231 characters long)
Context: ...onent has not yet been provisioned, the !terraform.state function will return `n...
(EN_EXCESSIVE_EXCLAMATION)
website/docs/functions/yaml/terraform.output.mdx
[typographical] ~81-~81: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
website/docs/functions/yaml/store.mdx
[typographical] ~100-~100: Consider using a typographic opening quote here.
Context: ...o, Atmos would attempt to merge a list (["subnet-111", "subnet-222"]) with a YAML...
(EN_QUOTES)
⏰ 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). (1)
- GitHub Check: Summary
🔇 Additional comments (18)
NOTICE (1)
186-186: Address the pipeline failure: NOTICE file out of date.The Dependency Review pipeline indicates the NOTICE file requires regeneration via
./scripts/generate-notice.sh. While the changes shown (smithy-go v1.23.2 → v1.24.0) appear correct, the regeneration script should be run locally to ensure all dependencies and their license metadata are properly reflected.Per coding guidelines, the NOTICE file is programmatically generated and should not be manually maintained. Please regenerate it using the script and commit the updated file.
Also applies to: 571-571
go.mod (1)
33-33: Dependency bump looks good.Minor version update to
github.com/aws/smithy-gofrom v1.23.2 to v1.24.0. This aligns with the NOTICE file updates and follows best practices for keeping dependencies current.website/docs/functions/index.mdx (1)
95-100: Formatting improvement on Migration Path table.Table alignment and padding adjustments enhance readability without changing content or mappings. Consistent with documentation best practices.
website/docs/functions/yaml/exec.mdx (2)
71-118: Deferred Evaluation section is clear and well-coordinated.The new documentation section effectively explains the three-phase merge process (Defer, Merge, Evaluate) with concrete examples that illustrate type conflict resolution. This aligns well with similar updates across other YAML function docs and fulfills the PR objective.
95-95: Minor typographical quote inconsistency flagged by linter.Line 95 uses straight double quotes in the code example. LanguageTool suggests using smart/typographic quotes for consistency. Consider reviewing the quote style across similar examples in related docs (store.mdx, env.mdx, template.mdx, terraform.output.mdx) for consistency.
website/docs/functions/yaml/store.mdx (2)
76-118: Deferred Evaluation documentation for!storeis consistent and well-explained.The section mirrors the structure and content quality of parallel updates in exec.mdx and other YAML function docs. The example effectively illustrates type conflicts (concrete list vs YAML function override).
100-100: Typographical quote inconsistency (opening quote).Similar to exec.mdx, LanguageTool flagged a quote style issue. Line 100 uses straight backtick-quote sequences where smart quotes may be expected. Ensure consistency across all YAML function documentation files.
website/docs/functions/yaml/env.mdx (2)
83-125: Deferred Evaluation documentation for!envis well-integrated.The section fits naturally after the Resolution Order section and before examples. It clearly explains the problem and three-phase solution with an appropriate example (database URL). Helpful cross-references to terraform.output docs for advanced quote handling.
107-107: Typographical quote inconsistency (closing quote).LanguageTool flagged a quote style issue at line 107. Consistent with similar issues in exec.mdx and store.mdx. Suggest reviewing all quote usages across the YAML function docs for consistency.
website/docs/functions/yaml/template.mdx (2)
142-183: Deferred Evaluation documentation for!templatemaintains consistency.The section follows the established pattern and includes a sophisticated example showing template evaluation deferral. Positioned logically before the Advanced Examples section.
166-166: Typographical quote inconsistency (opening quote).LanguageTool flagged a quote style issue at line 166 consistent with other YAML function docs. Review quote consistency across all updated documentation files.
website/docs/functions/yaml/terraform.output.mdx (3)
57-98: Deferred Evaluation section integrated cleanly.The section appears early in the document and establishes the three-phase merge process context before diving into function execution flow details. Consistent with documentation across other YAML functions.
194-196: Single-quote escape example directly addresses PR objective.Line 195 adds a concrete example of escaped single quotes (
app''s-name), fulfilling the PR objective to "document single-quote handling from PR #1560 consistently." The quote escaping rules section (lines 198-206) provides clear guidance on when to use single vs. double quotes, making the examples immediately actionable.
81-81: Typographical quote inconsistency (closing quote).LanguageTool flagged a quote style issue at line 81, consistent with similar issues across other YAML function docs. Consider a final pass to standardize quote styles.
website/docs/functions/yaml/terraform.state.mdx (3)
70-112: Clear deferred evaluation explanation with solid structure.The section effectively explains the type-conflict problem and defers-merge solution. The three-phase approach (Defer/Merge/Evaluate) is well-positioned. One minor suggestion: consider adding a brief note that this deferred behavior is automatic and requires no developer action, to avoid confusion about implementation requirements.
172-207: Quote handling section is comprehensive and actionable.The examples clearly show the bracket-notation pattern, escaping rules, and use of single-quote wrapping. The escaped-single-quote example (line 196:
'') is particularly valuable for edge cases. Cross-reference to!terraform.outputand!includereinforces consistency across functions.
209-254: Default value examples effectively demonstrate YQ//operator with proper escaping.The progression (string → list → map defaults) and double-quote escaping guidance are clear. Line 249 shows practical use of single-quote wrapping combined with defaults, which mirrors the earlier quote handling section nicely. The cross-reference to YQ documentation is helpful.
website/docs/functions/yaml/store.get.mdx (1)
81-123: Deferred evaluation section mirrors terraform.state.mdx structure—excellent consistency.The problem/solution format and benefits align perfectly across both files. The example cleanly shows the api_key conflict scenario, demonstrating practical applicability of deferred evaluation to store.get use cases. Section provides solid foundation for users new to this feature.
- Clarify that !terraform.state returns null when state file doesn't exist - Enhance YQ expression comments in store.get.mdx to be more specific 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
website/docs/functions/yaml/terraform.state.mdx (1)
172-207: Comprehensive quoting guidance improves clarity for complex YQ expressions.The expanded section with multiple real-world examples (lines 185-197) clearly demonstrates the single-quote wrapping pattern. The quote escaping rules summary (lines 199-203) is concise and actionable.
One suggestion: The note on line 220-224 in the "default values" section below mentions double-quoting for expressions with spaces and escaping within defaults. Consider cross-linking this note to the "Quote escaping rules" section (lines 199-203) to avoid readers feeling they're getting conflicting guidance about when to use which quoting style. Currently, a reader might not immediately see the connection between "wrap entire expression in single quotes" (line 201) and "double-quote if expression contains spaces" (line 220).
📜 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.
📒 Files selected for processing (2)
website/docs/functions/yaml/store.get.mdx(1 hunks)website/docs/functions/yaml/terraform.state.mdx(3 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in thewebsite/directory when adding new features, ensure consistency between CLI help text and website documentation, and follow the website's documentation structure and style
Keep website code in thewebsite/directory, follow the existing website architecture and style, and test website changes locally before committing
Keep CLI documentation and website documentation in sync and document new features on the website with examples and use cases
Files:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdx
🧠 Learnings (13)
📓 Common learnings
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.
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: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:40-213
Timestamp: 2024-12-03T05:18:49.169Z
Learning: In the context of the Atmos project, it's acceptable for functions like `execTerraformOutput` to remain as single functions if they perform a single purpose, such as retrieving Terraform outputs for a component in a stack, even if the function is lengthy.
📚 Learning: 2024-12-03T04:01:16.446Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:0-0
Timestamp: 2024-12-03T04:01:16.446Z
Learning: In the `terraform.output.mdx` documentation file (`website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx`), the cache invalidation and cache scope behavior for the `!terraform.output` function are already described.
Applied to files:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
Applied to files:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 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:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!include` allows downloading local or remote files from different sources and assigning their contents to sections in stack manifests. It supports various protocols (file, http, git, s3, etc.) and can filter content using YQ expressions.
Applied to files:
website/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-30T19:03:50.738Z
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2024-12-03T03:49:30.395Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:104-110
Timestamp: 2024-12-03T03:49:30.395Z
Learning: In the documentation for `!terraform.output`, warnings about template variable availability are already covered in other sections, so no need to suggest adding them here.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-02-18T13:13:11.497Z
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1068
File: tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden:59-64
Timestamp: 2025-02-18T13:13:11.497Z
Learning: For Atmos CLI help text, angle brackets in command examples and flag descriptions should be escaped using HTML entities (e.g., `<component>`) rather than converted to backticks or other markdown formatting.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-02-19T05:50:35.853Z
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1068
File: tests/snapshots/TestCLICommands_atmos_terraform_apply_--help.stdout.golden:0-0
Timestamp: 2025-02-19T05:50:35.853Z
Learning: Backtick formatting should only be applied to flag descriptions in Go source files, not in golden test files (test snapshots) as they are meant to capture the raw command output.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-24T22:20:39.209Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1505
File: website/docs/cli/commands/completion.mdx:124-127
Timestamp: 2025-09-24T22:20:39.209Z
Learning: In Docusaurus (specifically the cloudposse/atmos repository), backticks render correctly as code formatting even when used inside HTML elements like <dl>/<dt>/<dd> tags in MDX files. No need to replace with <code> tags.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 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:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2024-12-03T05:18:49.169Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:40-213
Timestamp: 2024-12-03T05:18:49.169Z
Learning: In the context of the Atmos project, it's acceptable for functions like `execTerraformOutput` to remain as single functions if they perform a single purpose, such as retrieving Terraform outputs for a component in a stack, even if the function is lengthy.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-27T20:50:20.564Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
🪛 LanguageTool
website/docs/functions/yaml/store.get.mdx
[typographical] ~105-~105: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("default-key-12345") with a YAML functio...
(EN_QUOTES)
website/docs/functions/yaml/terraform.state.mdx
[typographical] ~94-~94: Consider using a typographic close quote here.
Context: ... Atmos would attempt to merge a string ("10.0.0.0/16") with a YAML function refe...
(EN_QUOTES)
[typographical] ~174-~174: Consider using a typographic opening quote here.
Context: ...must wrap the key in double quotes like ["github-dependabot"]. This often clashes...
(EN_QUOTES)
[style] ~562-~562: Using many exclamation marks might seem excessive (in this case: 39 exclamation marks for a text that’s 15241 characters long)
Context: ...sn't exist (e.g., not yet provisioned), !terraform.state returns null. Use ...
(EN_EXCESSIVE_EXCLAMATION)
⏰ 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). (2)
- GitHub Check: Acceptance Tests (windows)
- GitHub Check: Summary
🔇 Additional comments (7)
website/docs/functions/yaml/terraform.state.mdx (3)
70-112: Deferred Evaluation section is well-structured and aligned with PR objectives.The three-phase approach (Defer, Merge, Evaluate) is clear and the problem/solution framing helps readers understand why this matters. The example effectively shows the type-conflict scenario. Consistency check: This section mirrors the structure in store.get.mdx as intended.
562-562: Defensive null-handling guidance aligns well with deferred evaluation section.Line 562 appropriately cross-references the default values guidance and reinforces the null-return behavior when a component isn't provisioned. This completes the user journey from understanding deferred evaluation to practical error handling.
144-145: Cross-reference to terraform.output execution flow assumes matching structure exists.Lines 144-145 reference the "!terraform.output Execution Flow" section. Per the PR objectives, terraform.output.mdx should have a parallel execution flow section. Verify this section exists and link anchors are correct when merging.
As a follow-up, confirm that
website/docs/functions/yaml/terraform.output.mdxhas both:
- A section titled "!terraform.output Function Execution Flow" (for anchor to work)
- Similar quoting examples as the ones in lines 179-197 of this file
This ensures users navigating between the two docs won't hit broken anchors.
website/docs/functions/yaml/store.get.mdx (4)
81-123: Deferred Evaluation section provides self-contained, parallel explanation to terraform.state.The structure mirrors terraform.state.mdx as intended (Defer → Merge → Evaluate phases), and the example scenario (api_key override with !store.get) is appropriately contextualized for store.get users. Benefits section is identical across docs, which aids consistency.
Note: The duplicate narrative across multiple function docs is intentional per PR objectives (each doc self-contained). This approach trades some maintenance burden for better UX—users don't need to jump between pages.
124-140: YQ Expressions section examples are clear and well-motivated.Lines 129-139 show practical store.get + query combinations (Redis, Azure, SSM). The comments (lines 131, 134, 137) explain intent clearly. Formatting is consistent with terraform.state.mdx.
142-197: Examples across Redis, SSM, Azure, and GSM stores demonstrate broad applicability.Lines 144-197 cover four distinct store backends with realistic use cases. Each example is self-contained and shows the progression from simple key retrieval to complex query + default patterns. Inline comments enhance clarity for readers unfamiliar with store mechanics.
199-207: Considerations section appropriately flags security and performance tradeoffs.The security note (line 206) mirrors terraform.state guidance. Performance and access-control notes add practical value. No gaps detected here.
|
@coderabbitai full review please |
|
@aknysh: I'll perform a full review of the documentation changes in this PR. 🧠 Learnings used✅ Actions performedFull review triggered. |
|
@aknysh: I'll perform a comprehensive review of the documentation changes now. 🧠 Learnings used✅ Actions performedFull review triggered. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
website/docs/reference/yaml-function-merging.mdx (1)
1-44: Solid intro and problem framing; address minor typographical polish.The frontmatter, introduction, and problem statement are clear and motivate the need for type-aware merging. The YAML code example effectively illustrates the type conflict scenario.
Three minor typographical/style items flagged by LanguageTool (lines 34, 42, 50):
- Line 34: Consider using a typographic close quote (""postgresql://localhost:5432/mydb"")
- Line 42: Try moving the adverb "always" closer to the verb: "as they have always been"
- Line 50: Consider using an em dash where listed
These are optional polish improvements for documentation consistency.
📜 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.
📒 Files selected for processing (9)
website/docs/functions/index.mdx(1 hunks)website/docs/functions/yaml/env.mdx(1 hunks)website/docs/functions/yaml/exec.mdx(1 hunks)website/docs/functions/yaml/store.get.mdx(1 hunks)website/docs/functions/yaml/store.mdx(1 hunks)website/docs/functions/yaml/template.mdx(1 hunks)website/docs/functions/yaml/terraform.output.mdx(2 hunks)website/docs/functions/yaml/terraform.state.mdx(3 hunks)website/docs/reference/yaml-function-merging.mdx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
website/**
📄 CodeRabbit inference engine (.cursor/rules/atmos-rules.mdc)
website/**: Update website documentation in thewebsite/directory when adding new features, ensure consistency between CLI help text and website documentation, and follow the website's documentation structure and style
Keep website code in thewebsite/directory, follow the existing website architecture and style, and test website changes locally before committing
Keep CLI documentation and website documentation in sync and document new features on the website with examples and use cases
Files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/exec.mdx
🧠 Learnings (20)
📓 Common learnings
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.
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: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:0-0
Timestamp: 2024-12-03T04:01:16.446Z
Learning: In the `terraform.output.mdx` documentation file (`website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx`), the cache invalidation and cache scope behavior for the `!terraform.output` function are already described.
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.
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
📚 Learning: 2024-12-03T04:01:16.446Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:0-0
Timestamp: 2024-12-03T04:01:16.446Z
Learning: In the `terraform.output.mdx` documentation file (`website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx`), the cache invalidation and cache scope behavior for the `!terraform.output` function are already described.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 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:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/exec.mdx
📚 Learning: 2024-12-03T03:49:30.395Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: website/docs/core-concepts/stacks/yaml-functions/terraform.output.mdx:104-110
Timestamp: 2024-12-03T03:49:30.395Z
Learning: In the documentation for `!terraform.output`, warnings about template variable availability are already covered in other sections, so no need to suggest adding them here.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-30T19:03:50.738Z
Learnt from: Cerebrovinny
Repo: cloudposse/atmos PR: 1560
File: pkg/utils/string_utils.go:43-64
Timestamp: 2025-09-30T19:03:50.738Z
Learning: In the Atmos codebase, YAML tags like !terraform.output rely on positional arguments, so the SplitStringByDelimiter function in pkg/utils/string_utils.go must preserve empty strings (even after trimming quotes) to maintain the correct number of positional arguments. Filtering out empty values after trimming would collapse the array and break these function calls.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2024-12-03T05:18:49.169Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:40-213
Timestamp: 2024-12-03T05:18:49.169Z
Learning: In the context of the Atmos project, it's acceptable for functions like `execTerraformOutput` to remain as single functions if they perform a single purpose, such as retrieving Terraform outputs for a component in a stack, even if the function is lengthy.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/index.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/exec.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!env` is used to retrieve environment variables and assign them to sections in stack manifests. It supports both simple types (string, number, boolean) and complex types (JSON-encoded lists, maps, objects).
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/index.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/exec.mdx
📚 Learning: 2024-12-03T05:29:07.718Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 810
File: internal/exec/terraform_utils.go:145-146
Timestamp: 2024-12-03T05:29:07.718Z
Learning: In the Atmos project, a 5-minute timeout in the `execTerraformOutput` function is acceptable for retrieving `terraform output` for a component in a stack.
Applied to files:
website/docs/functions/yaml/terraform.output.mdx
📚 Learning: 2025-01-19T22:30:27.600Z
Learnt from: aknysh
Repo: cloudposse/atmos PR: 0
File: :0-0
Timestamp: 2025-01-19T22:30:27.600Z
Learning: The Atmos YAML function `!include` allows downloading local or remote files from different sources and assigning their contents to sections in stack manifests. It supports various protocols (file, http, git, s3, etc.) and can filter content using YQ expressions.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/functions/yaml/store.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/store.get.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/env.mdxwebsite/docs/functions/yaml/exec.mdx
📚 Learning: 2025-09-27T20:50:20.564Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1533
File: pkg/config/load.go:585-637
Timestamp: 2025-09-27T20:50:20.564Z
Learning: In the cloudposse/atmos repository, command merging prioritizes precedence over display ordering. Help commands are displayed lexicographically regardless of internal array order, so the mergeCommandArrays function focuses on ensuring the correct precedence chain (top-level file wins) rather than maintaining specific display order.
Applied to files:
website/docs/functions/yaml/terraform.output.mdxwebsite/docs/functions/yaml/template.mdxwebsite/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/terraform.state.mdxwebsite/docs/functions/yaml/exec.mdx
📚 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:
website/docs/functions/yaml/template.mdx
📚 Learning: 2024-12-12T15:15:46.457Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 808
File: examples/demo-atmos-cli-imports/atmos.yaml:7-7
Timestamp: 2024-12-12T15:15:46.457Z
Learning: In example configuration files, such as `examples/demo-atmos-cli-imports/atmos.yaml`, it's acceptable to use `refs/heads/main` in remote URLs.
Applied to files:
website/docs/functions/yaml/template.mdx
📚 Learning: 2025-11-24T17:35:20.297Z
Learnt from: CR
Repo: cloudposse/atmos PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T17:35:20.297Z
Learning: Applies to internal/exec/template_funcs.go : New configs support Go templating with FuncMap() from internal/exec/template_funcs.go. Implement template functions in internal/exec/template_funcs.go, register them, add tests, and update documentation.
Applied to files:
website/docs/functions/index.mdx
📚 Learning: 2025-04-03T10:57:04.602Z
Learnt from: haitham911
Repo: cloudposse/atmos PR: 1091
File: pkg/config/load_config_args.go:61-82
Timestamp: 2025-04-03T10:57:04.602Z
Learning: In the Atmos configuration system, errors in `mergeDefaultImports` and `mergeImports` functions are intentionally only logged as debug messages without returning errors, as they are considered non-critical. Only errors in critical functions like `mergeConfigFile` are returned to halt execution.
Applied to files:
website/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/env.mdx
📚 Learning: 2025-03-17T18:41:08.831Z
Learnt from: haitham911
Repo: cloudposse/atmos PR: 1085
File: pkg/config/imports.go:68-75
Timestamp: 2025-03-17T18:41:08.831Z
Learning: In the Atmos configuration import system, errors during config file merging are logged at debug level and the process continues with other imports rather than failing completely, prioritizing resilience over strict correctness.
Applied to files:
website/docs/reference/yaml-function-merging.mdxwebsite/docs/functions/yaml/env.mdx
📚 Learning: 2025-02-18T13:13:11.497Z
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1068
File: tests/snapshots/TestCLICommands_atmos_terraform_help.stdout.golden:59-64
Timestamp: 2025-02-18T13:13:11.497Z
Learning: For Atmos CLI help text, angle brackets in command examples and flag descriptions should be escaped using HTML entities (e.g., `<component>`) rather than converted to backticks or other markdown formatting.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-02-19T05:50:35.853Z
Learnt from: samtholiya
Repo: cloudposse/atmos PR: 1068
File: tests/snapshots/TestCLICommands_atmos_terraform_apply_--help.stdout.golden:0-0
Timestamp: 2025-02-19T05:50:35.853Z
Learning: Backtick formatting should only be applied to flag descriptions in Go source files, not in golden test files (test snapshots) as they are meant to capture the raw command output.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-09-24T22:20:39.209Z
Learnt from: osterman
Repo: cloudposse/atmos PR: 1505
File: website/docs/cli/commands/completion.mdx:124-127
Timestamp: 2025-09-24T22:20:39.209Z
Learning: In Docusaurus (specifically the cloudposse/atmos repository), backticks render correctly as code formatting even when used inside HTML elements like <dl>/<dt>/<dd> tags in MDX files. No need to replace with <code> tags.
Applied to files:
website/docs/functions/yaml/terraform.state.mdx
📚 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:
website/docs/functions/yaml/terraform.state.mdx
📚 Learning: 2025-02-09T18:43:53.902Z
Learnt from: haitham911
Repo: cloudposse/atmos PR: 808
File: pkg/config/loader.go:141-145
Timestamp: 2025-02-09T18:43:53.902Z
Learning: In the Atmos configuration loading process, errors during individual config file loading/merging should be logged but not propagate up to break the entire process. This design choice enables resilient partial configuration loading.
Applied to files:
website/docs/functions/yaml/env.mdx
🪛 LanguageTool
website/docs/reference/yaml-function-merging.mdx
[typographical] ~34-~34: Consider using a typographic close quote here.
Context: ...RLis a different type than the string"postgresql://localhost:5432/mydb"`. With...
(EN_QUOTES)
[style] ~42-~42: To make your writing flow more naturally, try moving the adverb ‘always’ closer to the verb ‘been’.
Context: ...final step in stack processing, as they always have been This approach ensures that YAML functi...
(PERF_TENS_ADV_PLACEMENT)
[typographical] ~50-~50: To join two clauses or introduce examples, consider using an em dash.
Context: ...erging: - !env - Environment variables - [!exec](/funct...
(DASH_RULE)
website/docs/functions/yaml/terraform.state.mdx
[typographical] ~136-~136: Consider using a typographic opening quote here.
Context: ...must wrap the key in double quotes like ["github-dependabot"]. This often clashes...
(EN_QUOTES)
[style] ~524-~524: Using many exclamation marks might seem excessive (in this case: 33 exclamation marks for a text that’s 13765 characters long)
Context: ...sn't exist (e.g., not yet provisioned), !terraform.state returns null. Use ...
(EN_EXCESSIVE_EXCLAMATION)
⏰ 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). (1)
- GitHub Check: Summary
🔇 Additional comments (15)
website/docs/reference/yaml-function-merging.mdx (2)
36-64: Clear solution explanation and comprehensive supported functions list.The type-aware merging solution is well-articulated, and the supported functions list is complete and well-linked. Benefits are practical and help readers understand the "why" behind the feature.
Note: The clarification on line 42–43 that "YAML functions are evaluated as the final step in stack processing, as they always have been"–directly addresses prior documentation concerns and is accurate per the codebase learnings.
65-87: Example is practical and clearly demonstrates type-aware merging benefit.The mixed static/dynamic value example is realistic and reinforces the "why" behind the feature. Comments are helpful.
website/docs/functions/index.mdx (1)
95-100: Minor table formatting adjustment; no content changes.The Migration Path table reformatting improves readability without altering the function recommendations or migration guidance. No issues detected.
website/docs/functions/yaml/env.mdx (1)
83-86: Type-Aware Merging note is appropriately concise and well-placed.The note is short, contextually relevant, and links to the central reference page. Placement after the Resolution Order section makes sense—readers understand how
!envresolves, then learn it can coexist with other types.website/docs/functions/yaml/store.get.mdx (1)
81-84: Type-Aware Merging note is consistent and well-placed after feature comparison.Note placement after the Key Differences section is logical. Readers understand
!store.getsemantics, then learn about inheritance/merging behavior.website/docs/functions/yaml/exec.mdx (1)
71-74: Type-Aware Merging note is consistently placed and appropriately concise.Placement after the templating capability tip makes sense. Reader understands function mechanics, then learns about inheritance behavior.
website/docs/functions/yaml/template.mdx (1)
142-145: Type-Aware Merging note is appropriately positioned and consistent.Placement before Advanced Examples is logical—reader understands the function's purpose, then learns about inheritance/merging behavior. Note format is consistent across all YAML function docs.
website/docs/functions/yaml/store.mdx (1)
76-79: Type-Aware Merging note is appropriately placed and maintains consistency.Placement after core usage/arguments and before feature depth (YQ expressions) is logical. Reader understands the function, then learns about inheritance/merging behavior.
website/docs/functions/yaml/terraform.output.mdx (2)
57-60: Type-Aware Merging note is consistently placed.Placement after templating capability and before the execution flow section is logical. Reader understands function mechanics, then learns about inheritance behavior.
156-158: Single-quote escaping example is practical and well-integrated.The new example (
'.apps["app''s-name"].display_name') demonstrates the escaping rule (line 164) in a concrete use case. Placement alongside other bracket-notation examples (lines 141, 148, 151, 154) is logical and reinforces the pattern.website/docs/functions/yaml/terraform.state.mdx (5)
70-73: Type-Aware Merging note integrates cleanly.The new explanatory note is well-positioned and provides the centralized reference as intended by the PR.
134-169: Bracket notation and quote escaping guidance is comprehensive and technically sound.The single-quote wrapping pattern (lines 138–143) is clearly explained, and the practical examples (lines 145–159) cover the main use cases: special characters, nested maps, stack templating, and single-quote escaping. The formal "Quote escaping rules" (lines 161–165) serve as a handy reference, and the tip (lines 167–169) correctly notes that this pattern applies to other YAML functions.
171-216: Default value section properly addresses null handling with YQ//operator.The examples at lines 195, 203, and 211 are technically accurate and demonstrate the correct escaping of double quotes within default values. The note at lines 182–186 clearly explains the double-quote escaping requirement, making the section self-contained.
524-525: Cold-start guidance updated with accurate null semantics.The revised text correctly states that
!terraform.statereturnsnull(rather than describing a terraform output failure) and directs readers to the default value section for handling unprovisioned components.
136-136: LanguageTool quote flag is a false positive.The opening quote in the inline code example
["github-dependabot"]is an ASCII straight quote (U+0022), not a typographic curly quote. This was verified in prior review comments and is the correct choice for technical documentation. No change needed.
what
/reference/yaml-function-mergingdocumenting type-aware merging of YAML functions!template,!env,!exec,!store,!store.get,!terraform.output,!terraform.state) linking to the reference page!terraform.statedocumentation with comprehensive single quotes examples (replaced brief reference with full examples)!terraform.outputdocumentation!terraform.outputand!terraform.statedocs self-contained with parallel structurewhy
!terraform.statedocumentation previously just referenced!terraform.outputdocs, requiring users to jump between pagesreferences
!terraform.outputshould support single quotes with nested double quotesSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.