Introduce Atmos YAML functions !include and !env

[aknysh]

what

• Introduce Atmos YAML functions !include and !env
• Add docs
  • https://pr-943.atmos-docs.ue2.dev.plat.cloudposse.org/core-concepts/stacks/yaml-functions/env/
  • https://pr-943.atmos-docs.ue2.dev.plat.cloudposse.org/core-concepts/stacks/yaml-functions/include/

why

• The !env YAML function is used to retrieve environment variables and assign them to the sections in Atmos stack manifests

• The !include YAML function allows downloading local or remote files from different sources, and assigning the file contents or individual values to the sections in Atmos stack manifests

description

!env Atmos YAML function

The !env Atmos YAML function is used to retrieve environment variables and assign them to the sections in Atmos stack manifests.

  # Get the value of an environment variable.
  # If the environment variable is not present in the environment, `null` will be assigned
  !env <env-var-name>

  # Get the value of an environment variable.
  # If the environment variable is not present in the environment, the `default-value` will be assigned
  !env <env-var-name> <default-value>

If the function is called with one argument (the name of the environment variable), and the environment variable is
not present, null will be assigned to the corresponding section in the Atmos manifest.

If the function is called with two arguments (the name of the environment variable and the default value), and the
environment variable is not present, the default value will be assigned to the corresponding section in the Atmos manifest.

Examples:

vars:
  # `api_key` will be set to `null` if the environment variable `API_KEY` is not present in the environment
  api_key: !env API_KEY
  # `app_name` will be set to the default value `my-app` if the environment variable `APP_NAME` is not present in the environment
  app_name: !env APP_NAME my-app

settings:
  # `provisioned_by_user` will be set to `null` if the environment variable `ATMOS_USER` is not present in the environment
  provisioned_by_user: !env ATMOS_USER

Handling default values with spaces:

If you need to provide default values with spaces, enclose them in double quotes and use single quotes around the whole expression.

For example:

  # `app_name` will be set to the default value `my app` if the environment variable `APP_NAME` is not present in the environment
  app_name: !env 'APP_NAME "my app"'

  # `app_description` will be set to the default value `my app description` if the environment variable `APP_DESCRIPTION` is not present in the environment
  app_description: !env 'APP_DESCRIPTION "my app description"'

!include Atmos YAML function

The !include Atmos YAML function allows downloading local or remote files from different sources, and assigning the file contents or individual values to the sections in Atmos stack manifests.

The !include function can be called with either one or two parameters:

  # Download the file and assign its content to the variable
  !include <file-path>

  # Download the file, filter the content using the YQ expression,
  # and assign the result to the variable
  !include <file-path> <yq-expression>

Examples:

components:
  terraform:
    my-component:
      vars:
        # Include a local file with the path relative to the current Atmos manifest
        values: !include ./values.yaml
        # Include a local file with the path relative to the current Atmos manifest and query the `vars.ipv4_primary_cidr_block` value from the file using YQ
        ipv4_primary_cidr_block: !include ./vpc_config.yaml .vars.ipv4_primary_cidr_block
        # Include a local file relative to the `base_path` setting in `atmos.yaml`
        vpc_defaults: !include stacks/catalog/vpc/defaults.yaml
        # Include a local file in HCL format
        hcl_values: !include ./values.hcl
        # Include a local file in HCL format with Terraform variables
        tfvars_values: !include ../components/terraform/vpc/vpc.tfvars
        # Include a local Markdown file
        description: !include ./description.md
        # Include a local text file
        text: !include a.txt
        # Include a local text file with spaces in the file name
        text2: !include '"my config.txt"'
        # Include a local text file on Windows with spaces in the file name, and get the `config.tests` value from the file
        tests: !include '"~/My Documents/dev/tests.yaml" .config.tests'
        # Download and include a remote YAML file using HTTPS protocol, and query the `vars` section from the file
        region_values: !include https://raw.githubusercontent.com/cloudposse/atmos/refs/heads/main/examples/quick-start-advanced/stacks/mixins/region/us-east-2.yaml .vars
        # Download and include a remote JSON file and query the `api` section from the file
        allowed_ips: !include https://api.github.com/meta .api
      settings:
        config:
          # Include a local JSON file and query the `user_id` variable from the file
          user_id: !include ./user_config.json .user_id

Description:

The YAML standard provides anchors and aliases, that allow you
to reuse and reference pieces of your YAML file, making it more efficient and reducing duplication.

Atmos supports YAML anchors and aliases, but the biggest limitation is that they are only available within the file in
which they are defined. You cannot reuse anchors across different files.

The !include Atmos YAML function overcomes this limitation by allowing you to include the content or individual values
from different local and remote sources. The !include function also provides the following features:

• Supports local files with absolute and relative paths

• Supports the remote protocols provided by the go-getter library

• Allows you to use YQ expressions to query and filter the content of the files to retrieve individual values

• Automatically detects the format of the files regardless of the file extensions. It supports files in JSON, YAML and HCL (tfvars) formats, and automatically converts them into correct YAML structures (simple and complex types like maps and lists are supported). All other files are returned unchanged, allowing you, for example, to include text and Markdown files as strings in Atmos manifests

Supported File Protocols:

The !include function supports the following local file paths:

• absolute paths (e.g. /Users/me/Documents/values.yaml)
• paths relative to the current Atmos manifest where the !include function is executed (e.g. ./values.yaml, ../config/values.yaml)
• paths relative to the base_path defined in atmos.yaml CLI config file (e.g. stacks/catalog/vpc/defaults.yaml)

To download remote files from different sources, the !include function uses go-getter
(used by Terraform for downloading modules) and supports the following protocols:

• tar - Tar files, potentially compressed (tar.gz, tar.bz2, etc.)
• zip - Zip files
• http - HTTP URLs
• https - HTTPS URLs
• git - Git repositories, which can be accessed via HTTPS or SSH
• hg - Mercurial repositories, accessed via HTTP/S or SSH
• s3 - Amazon S3 bucket URLs
• gcs - Google Cloud Storage URLs
• oci - Open Container Initiative (OCI) images
• scp - Secure Copy Protocol for SSH-based transfers
• sftp - SSH File Transfer Protocol

Using YQ Expressions to retrieve individual values from files:

To retrieve individual values from complex types such as maps and lists, or do any kind of filtering or querying,
you can utilize YQ expressions.

For example:

• Retrieve the first item from a list

subnet_id1: !include <file-path> .private_subnet_ids[0]

• Read a key from a map

username: !include <file-path> .config_map.username

For more details, review the following docs:

• YQ Guide
• YQ Recipes

Handling file paths and YQ expressions with spaces:

If you have spaces in the file names or the YQ expressions, enclose the file path and YQ expression in double quotes and
the whole expression in single quotes.

For example, on Windows:

  vars:
    values: !include '"~/My Documents/dev/values.yaml"'
    config: !include '"~/My Documents/dev/config.json" "<yq-expression-with-spaces>"'

On macOS and Linux:

  vars:
    values: !include './values.yaml "<yq-expression-with-spaces>"'
    description: !include '"component description.md"'

Summary by CodeRabbit

Atmos v1.153.0 Release Notes

• New Features

  • Added !env YAML function to retrieve environment variables in stack manifests.
  • Added !include YAML function to download and include local/remote files in stack manifests.
  • Introduced processTagEnv and processTagInclude functions for enhanced YAML processing.
  • Added !store YAML function for reading values from a remote store in Atmos stack manifests.

• Improvements

  • Updated dependency versions for AWS SDK and related libraries.
  • Enhanced file handling and path resolution utilities.
  • Improved error handling and logging for file and configuration processing.
  • Updated Atmos CLI version in GitHub Actions workflow.

• Bug Fixes

  • Refined file path sanitization for cross-platform compatibility.
  • Improved handling of configuration file imports and references.

• Documentation

  • Added comprehensive documentation for new YAML functions.
  • Updated integration guides and usage examples.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (4)

website/docs/core-concepts/stacks/yaml-functions/include.mdx (1)

89-99: Add period at the end of the paragraph.

The features list is comprehensive, but the last paragraph is missing a period.

  All other files are returned unchanged, allowing you, for example, to include text and
- [Markdown](https://www.markdownguide.org/) files as strings in Atmos manifests
+ [Markdown](https://www.markdownguide.org/) files as strings in Atmos manifests.

🧰 Tools

🪛 LanguageTool

[grammar] ~99-~99: Please add a punctuation mark at the end of paragraph.
Context: ...wnguide.org/) files as strings in Atmos manifests ## Supported File Protocols The `!inc...

(PUNCTUATION_PARAGRAPH_END)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (3)

19-27: Enhance usage documentation with type support and behavior details.

The usage section would benefit from additional clarity about:

1. Supported value types (simple scalars vs complex types)
2. Explicit behavior when environment variables are not set

  # Get the value of an environment variable.
  # If the environment variable is not set, `null` will be assigned
+ # Supports simple scalar values (string, number, boolean)
  !env <env-var-name>

  # Get the value of an environment variable.
  # If the environment variable is not set, the `default-value` will be assigned
+ # The default value must be a simple scalar
  !env <env-var-name> <default-value>

---

43-50: Add more comprehensive examples.

Consider adding examples that demonstrate:

1. Different value types (string, number, boolean)
2. Behavior when env var is not set (returns null)

 vars:
   api_key: !env API_KEY
   is_test: !env IS_TEST false
+  # Examples with different types
+  port: !env PORT 8080        # number
+  debug: !env DEBUG true      # boolean
+  unset_var: !env UNSET_VAR  # returns null

 settings:
   provisioned_by_user: !env USER

---

62-66: Clarify template processing order.

The tip about template processing would benefit from a concrete example to illustrate the order of operations.

 :::tip
 You can use [Atmos Stack Manifest Templating](/core-concepts/stacks/templates) in the environment variable names and default values when calling the `!env` YAML function.
 Atmos processes the templates first, and then executes the `!env` function, allowing you to provide the parameters to
 the function dynamically.
+
+ For example:
+ ```yaml
+ region: !env '${component.region}_ENDPOINT'  # Template is processed first
+ ```
 :::

🧰 Tools

🪛 LanguageTool

[style] ~64-~64: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 705 characters long)
Context: ... templates first, and then executes the !env function, allowing you to provide t...

(EN_EXCESSIVE_EXCLAMATION)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b4aa96d and b794be2.

📒 Files selected for processing (3)

• internal/exec/yaml_func_env.go (1 hunks)
• website/docs/core-concepts/stacks/yaml-functions/env.mdx (1 hunks)
• website/docs/core-concepts/stacks/yaml-functions/include.mdx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/exec/yaml_func_env.go

🧰 Additional context used

📓 Learnings (2)

website/docs/core-concepts/stacks/yaml-functions/include.mdx (1)

Learnt from: aknysh
PR: cloudposse/atmos#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.

website/docs/core-concepts/stacks/yaml-functions/env.mdx (1)

Learnt from: aknysh
PR: cloudposse/atmos#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).

🪛 LanguageTool

website/docs/core-concepts/stacks/yaml-functions/include.mdx

[grammar] ~99-~99: Please add a punctuation mark at the end of paragraph.
Context: ...wnguide.org/) files as strings in Atmos manifests ## Supported File Protocols The `!inc...

(PUNCTUATION_PARAGRAPH_END)

---

[style] ~104-~104: A comma is missing here.
Context: ...g local file paths: - absolute paths (e.g. /Users/me/Documents/values.yaml) - ...

(EG_NO_COMMA)

---

[style] ~105-~105: A comma is missing here.
Context: ...re the !include function is executed (e.g. ./values.yaml, `../config/values.yaml...

(EG_NO_COMMA)

---

[style] ~106-~106: A comma is missing here.
Context: ...efined in atmos.yaml CLI config file (e.g. stacks/catalog/vpc/defaults.yaml) To...

(EG_NO_COMMA)

---

[typographical] ~111-~111: To join two clauses or introduce examples, consider using an em dash.
Context: ...pports the following protocols: - tar - Tar files, potentially compressed (tar.g...

(DASH_RULE)

---

[typographical] ~112-~112: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpressed (tar.gz, tar.bz2, etc.) - zip - Zip files - http - HTTP URLs - https...

(DASH_RULE)

---

[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ....bz2, etc.) - zip - Zip files - http - HTTP URLs - https - HTTPS URLs - git...

(DASH_RULE)

---

[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...Zip files - http - HTTP URLs - https - HTTPS URLs - git - Git repositories, w...

(DASH_RULE)

---

[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...HTTP URLs - https - HTTPS URLs - git - Git repositories, which can be accessed ...

(DASH_RULE)

---

[typographical] ~116-~116: To join two clauses or introduce examples, consider using an em dash.
Context: ... can be accessed via HTTPS or SSH - hg - Mercurial repositories, accessed via HTT...

(DASH_RULE)

---

[typographical] ~117-~117: To join two clauses or introduce examples, consider using an em dash.
Context: ...ories, accessed via HTTP/S or SSH - s3 - Amazon S3 bucket URLs - gcs - Google C...

(DASH_RULE)

---

[typographical] ~118-~118: To join two clauses or introduce examples, consider using an em dash.
Context: ...H - s3 - Amazon S3 bucket URLs - gcs - Google Cloud Storage URLs - oci - Open...

(DASH_RULE)

---

[typographical] ~119-~119: To join two clauses or introduce examples, consider using an em dash.
Context: ...gcs- Google Cloud Storage URLs -oci` - Open Container Initiative (OCI) images -...

(DASH_RULE)

---

[typographical] ~120-~120: To join two clauses or introduce examples, consider using an em dash.
Context: ...ontainer Initiative (OCI) images - scp - Secure Copy Protocol for SSH-based trans...

(DASH_RULE)

---

[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...rotocol for SSH-based transfers - sftp - SSH File Transfer Protocol :::tip You c...

(DASH_RULE)

---

[style] ~125-~125: Using many exclamation marks might seem excessive (in this case: 8 exclamation marks for a text that’s 3718 characters long)
Context: ... templates first, and then executes the !include function, allowing you to provi...

(EN_EXCESSIVE_EXCLAMATION)

website/docs/core-concepts/stacks/yaml-functions/env.mdx

[style] ~64-~64: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 705 characters long)
Context: ... templates first, and then executes the !env function, allowing you to provide t...

(EN_EXCESSIVE_EXCLAMATION)

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: Build (windows-latest, windows)
• GitHub Check: Summary

🔇 Additional comments (6)

website/docs/core-concepts/stacks/yaml-functions/include.mdx (5)

12-14: LGTM! Clear and concise introduction.

The introduction effectively communicates the purpose and capabilities of the !include function.

---

16-27: Add error handling documentation.

While the usage section is clear, it would be beneficial to document how errors are handled and displayed.

Based on the past review comments where @osterman asked about error handling and @aknysh confirmed errors are shown in the console, let's add this information to the documentation.

  # and assign the result to the variable
  !include <file-path> <yq-expression>
+
+:::note
+All errors that occur during file inclusion (e.g., file not found, permission denied, invalid YQ expression)
+are displayed in the console with detailed error messages.
+:::

---

49-75: LGTM! Comprehensive examples covering various use cases.

The examples section effectively demonstrates:

• Local and remote file inclusion
• Different file formats (YAML, HCL, JSON, Markdown, text)
• Path handling with spaces
• YQ expressions for value extraction

---

111-121: Consider adding security considerations for each protocol.

While the protocols are well-documented, adding security considerations would be valuable.

Based on the past review comments where this was suggested and @aknysh mentioned it could be added in a separate PR, I'll skip proposing the changes here.

🧰 Tools

🪛 LanguageTool

[typographical] ~111-~111: To join two clauses or introduce examples, consider using an em dash.
Context: ...pports the following protocols: - tar - Tar files, potentially compressed (tar.g...

(DASH_RULE)

---

[typographical] ~112-~112: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpressed (tar.gz, tar.bz2, etc.) - zip - Zip files - http - HTTP URLs - https...

(DASH_RULE)

---

[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ....bz2, etc.) - zip - Zip files - http - HTTP URLs - https - HTTPS URLs - git...

(DASH_RULE)

---

[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...Zip files - http - HTTP URLs - https - HTTPS URLs - git - Git repositories, w...

(DASH_RULE)

---

[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...HTTP URLs - https - HTTPS URLs - git - Git repositories, which can be accessed ...

(DASH_RULE)

---

[typographical] ~116-~116: To join two clauses or introduce examples, consider using an em dash.
Context: ... can be accessed via HTTPS or SSH - hg - Mercurial repositories, accessed via HTT...

(DASH_RULE)

---

[typographical] ~117-~117: To join two clauses or introduce examples, consider using an em dash.
Context: ...ories, accessed via HTTP/S or SSH - s3 - Amazon S3 bucket URLs - gcs - Google C...

(DASH_RULE)

---

[typographical] ~118-~118: To join two clauses or introduce examples, consider using an em dash.
Context: ...H - s3 - Amazon S3 bucket URLs - gcs - Google Cloud Storage URLs - oci - Open...

(DASH_RULE)

---

[typographical] ~119-~119: To join two clauses or introduce examples, consider using an em dash.
Context: ...gcs- Google Cloud Storage URLs -oci` - Open Container Initiative (OCI) images -...

(DASH_RULE)

---

[typographical] ~120-~120: To join two clauses or introduce examples, consider using an em dash.
Context: ...ontainer Initiative (OCI) images - scp - Secure Copy Protocol for SSH-based trans...

(DASH_RULE)

---

[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...rotocol for SSH-based transfers - sftp - SSH File Transfer Protocol :::tip You c...

(DASH_RULE)

---

154-172: LGTM! Clear instructions for handling special cases.

The section on handling file paths and YQ expressions with spaces is well-documented with clear examples for both Windows and Unix-like systems.

website/docs/core-concepts/stacks/yaml-functions/env.mdx (1)

1-6: Well-structured frontmatter!

The metadata is clear and comprehensive, providing good context for the documentation.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (1)

57-57: Consider using a more universal environment variable example.

The USER environment variable might not be available in all environments (e.g., containerized environments). Consider using a more universal example like HOSTNAME or a custom application-specific variable like ATMOS_USER.

website/docs/core-concepts/stacks/yaml-functions/include.mdx (2)

99-99: Add missing punctuation at the end of the paragraph.

Please add a period at the end of the paragraph on line 99 to enhance readability.

🧰 Tools

🪛 LanguageTool

[grammar] ~99-~99: Please add a punctuation mark at the end of paragraph.
Context: ...wnguide.org/) files as strings in Atmos manifests ## Supported File Protocols The `!inc...

(PUNCTUATION_PARAGRAPH_END)

---

104-106: Include commas after 'e.g.' in examples.

Adding commas after 'e.g.' improves clarity in your examples.

Apply this diff:

-      - absolute paths (e.g. `/Users/me/Documents/values.yaml`)
+      - absolute paths (e.g., `/Users/me/Documents/values.yaml`)
-      - paths relative to the current Atmos manifest where the `!include` function is executed (e.g. `./values.yaml`, `../config/values.yaml`)
+      - paths relative to the current Atmos manifest where the `!include` function is executed (e.g., `./values.yaml`, `../config/values.yaml`)
-      - paths relative to the [`base_path`](/cli/configuration/#base-path) defined in `atmos.yaml` CLI config file (e.g. `stacks/catalog/vpc/defaults.yaml`)
+      - paths relative to the [`base_path`](/cli/configuration/#base-path) defined in `atmos.yaml` CLI config file (e.g., `stacks/catalog/vpc/defaults.yaml`)

🧰 Tools

🪛 LanguageTool

[style] ~104-~104: A comma is missing here.
Context: ...g local file paths: - absolute paths (e.g. /Users/me/Documents/values.yaml) - ...

(EG_NO_COMMA)

---

[style] ~105-~105: A comma is missing here.
Context: ...re the !include function is executed (e.g. ./values.yaml, `../config/values.yaml...

(EG_NO_COMMA)

---

[style] ~106-~106: A comma is missing here.
Context: ...efined in atmos.yaml CLI config file (e.g. stacks/catalog/vpc/defaults.yaml) To...

(EG_NO_COMMA)

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b794be2 and 8fec4a8.

📒 Files selected for processing (4)

• internal/exec/yaml_func_env.go (1 hunks)
• internal/exec/yaml_func_include.go (1 hunks)
• website/docs/core-concepts/stacks/yaml-functions/env.mdx (1 hunks)
• website/docs/core-concepts/stacks/yaml-functions/include.mdx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• internal/exec/yaml_func_env.go

🧰 Additional context used

📓 Learnings (2)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (1)

Learnt from: aknysh
PR: cloudposse/atmos#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/core-concepts/stacks/yaml-functions/include.mdx (1)

Learnt from: aknysh
PR: cloudposse/atmos#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.

🪛 LanguageTool

website/docs/core-concepts/stacks/yaml-functions/env.mdx

[style] ~76-~76: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1153 characters long)
Context: ... templates first, and then executes the !env function, allowing you to provide t...

(EN_EXCESSIVE_EXCLAMATION)

website/docs/core-concepts/stacks/yaml-functions/include.mdx

[grammar] ~99-~99: Please add a punctuation mark at the end of paragraph.
Context: ...wnguide.org/) files as strings in Atmos manifests ## Supported File Protocols The `!inc...

(PUNCTUATION_PARAGRAPH_END)

---

[style] ~104-~104: A comma is missing here.
Context: ...g local file paths: - absolute paths (e.g. /Users/me/Documents/values.yaml) - ...

(EG_NO_COMMA)

---

[style] ~105-~105: A comma is missing here.
Context: ...re the !include function is executed (e.g. ./values.yaml, `../config/values.yaml...

(EG_NO_COMMA)

---

[style] ~106-~106: A comma is missing here.
Context: ...efined in atmos.yaml CLI config file (e.g. stacks/catalog/vpc/defaults.yaml) To...

(EG_NO_COMMA)

---

[typographical] ~111-~111: To join two clauses or introduce examples, consider using an em dash.
Context: ...pports the following protocols: - tar - Tar files, potentially compressed (tar.g...

(DASH_RULE)

---

[typographical] ~112-~112: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpressed (tar.gz, tar.bz2, etc.) - zip - Zip files - http - HTTP URLs - https...

(DASH_RULE)

---

[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ....bz2, etc.) - zip - Zip files - http - HTTP URLs - https - HTTPS URLs - git...

(DASH_RULE)

---

[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...Zip files - http - HTTP URLs - https - HTTPS URLs - git - Git repositories, w...

(DASH_RULE)

---

[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...HTTP URLs - https - HTTPS URLs - git - Git repositories, which can be accessed ...

(DASH_RULE)

---

[typographical] ~116-~116: To join two clauses or introduce examples, consider using an em dash.
Context: ... can be accessed via HTTPS or SSH - hg - Mercurial repositories, accessed via HTT...

(DASH_RULE)

---

[typographical] ~117-~117: To join two clauses or introduce examples, consider using an em dash.
Context: ...ories, accessed via HTTP/S or SSH - s3 - Amazon S3 bucket URLs - gcs - Google C...

(DASH_RULE)

---

[typographical] ~118-~118: To join two clauses or introduce examples, consider using an em dash.
Context: ...H - s3 - Amazon S3 bucket URLs - gcs - Google Cloud Storage URLs - oci - Open...

(DASH_RULE)

---

[typographical] ~119-~119: To join two clauses or introduce examples, consider using an em dash.
Context: ...gcs- Google Cloud Storage URLs -oci` - Open Container Initiative (OCI) images -...

(DASH_RULE)

---

[typographical] ~120-~120: To join two clauses or introduce examples, consider using an em dash.
Context: ...ontainer Initiative (OCI) images - scp - Secure Copy Protocol for SSH-based trans...

(DASH_RULE)

---

[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...rotocol for SSH-based transfers - sftp - SSH File Transfer Protocol :::tip You c...

(DASH_RULE)

---

[style] ~125-~125: Using many exclamation marks might seem excessive (in this case: 8 exclamation marks for a text that’s 3716 characters long)
Context: ... templates first, and then executes the !include function, allowing you to provi...

(EN_EXCESSIVE_EXCLAMATION)

⏰ Context from checks skipped due to timeout of 90000ms (2)

• GitHub Check: Acceptance Tests (windows-latest, windows)
• GitHub Check: Summary

🔇 Additional comments (6)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (4)

1-13: Well-structured frontmatter and introduction!

The metadata and introduction clearly communicate the purpose of the !env function.

---

15-46: Clear documentation of function behavior!

The usage and arguments sections effectively communicate:

• Function parameters and their purpose
• Behavior when environment variables are not set
• Default value handling

---

60-72: Clear explanation of quoting requirements!

The documentation effectively demonstrates how to handle default values containing spaces using appropriate quoting.

---

74-78: Helpful tip about template processing order!

The tip effectively explains how the !env function integrates with Atmos Stack Manifest Templating, clarifying that templates are processed before the function executes.

🧰 Tools

🪛 LanguageTool

[style] ~76-~76: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1153 characters long)
Context: ... templates first, and then executes the !env function, allowing you to provide t...

(EN_EXCESSIVE_EXCLAMATION)

internal/exec/yaml_func_include.go (1)

1-66: Code looks great!

The processTagInclude function is well-structured with proper error handling and logging. It aligns well with the project's standards.

website/docs/core-concepts/stacks/yaml-functions/include.mdx (1)

111-121: Use em dashes instead of hyphens in the protocol list.

Replacing hyphens with em dashes enhances readability in your list of supported protocols.

Apply this diff:

-    - `tar` - Tar files, potentially compressed (tar.gz, tar.bz2, etc.)
+    - `tar` — Tar files, potentially compressed (tar.gz, tar.bz2, etc.)

Repeat for lines 112-121.

🧰 Tools

🪛 LanguageTool

[typographical] ~111-~111: To join two clauses or introduce examples, consider using an em dash.
Context: ...pports the following protocols: - tar - Tar files, potentially compressed (tar.g...

(DASH_RULE)

---

[typographical] ~112-~112: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpressed (tar.gz, tar.bz2, etc.) - zip - Zip files - http - HTTP URLs - https...

(DASH_RULE)

---

[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ....bz2, etc.) - zip - Zip files - http - HTTP URLs - https - HTTPS URLs - git...

(DASH_RULE)

---

[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...Zip files - http - HTTP URLs - https - HTTPS URLs - git - Git repositories, w...

(DASH_RULE)

---

[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...HTTP URLs - https - HTTPS URLs - git - Git repositories, which can be accessed ...

(DASH_RULE)

---

[typographical] ~116-~116: To join two clauses or introduce examples, consider using an em dash.
Context: ... can be accessed via HTTPS or SSH - hg - Mercurial repositories, accessed via HTT...

(DASH_RULE)

---

[typographical] ~117-~117: To join two clauses or introduce examples, consider using an em dash.
Context: ...ories, accessed via HTTP/S or SSH - s3 - Amazon S3 bucket URLs - gcs - Google C...

(DASH_RULE)

---

[typographical] ~118-~118: To join two clauses or introduce examples, consider using an em dash.
Context: ...H - s3 - Amazon S3 bucket URLs - gcs - Google Cloud Storage URLs - oci - Open...

(DASH_RULE)

---

[typographical] ~119-~119: To join two clauses or introduce examples, consider using an em dash.
Context: ...gcs- Google Cloud Storage URLs -oci` - Open Container Initiative (OCI) images -...

(DASH_RULE)

---

[typographical] ~120-~120: To join two clauses or introduce examples, consider using an em dash.
Context: ...ontainer Initiative (OCI) images - scp - Secure Copy Protocol for SSH-based trans...

(DASH_RULE)

---

[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...rotocol for SSH-based transfers - sftp - SSH File Transfer Protocol :::tip You c...

(DASH_RULE)

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (1)

17-27: Add error handling documentation to the usage section.

The usage section would benefit from documenting how errors are handled and displayed to users. Consider adding examples of common error scenarios and their corresponding error messages.

website/docs/core-concepts/stacks/yaml-functions/include.mdx (1)

18-27: Add security considerations to the usage section.

Consider adding security best practices for handling sensitive files and using remote protocols. Include recommendations for:

• File permissions
• URL validation
• Authentication handling

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8fec4a8 and 96e2d3d.

📒 Files selected for processing (2)

• website/docs/core-concepts/stacks/yaml-functions/env.mdx (1 hunks)
• website/docs/core-concepts/stacks/yaml-functions/include.mdx (1 hunks)

🧰 Additional context used

📓 Learnings (2)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (1)

Learnt from: aknysh
PR: cloudposse/atmos#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/core-concepts/stacks/yaml-functions/include.mdx (1)

Learnt from: aknysh
PR: cloudposse/atmos#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.

🪛 LanguageTool

website/docs/core-concepts/stacks/yaml-functions/env.mdx

[style] ~77-~77: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1154 characters long)
Context: ... templates first, and then executes the !env function, allowing you to provide t...

(EN_EXCESSIVE_EXCLAMATION)

website/docs/core-concepts/stacks/yaml-functions/include.mdx

[typographical] ~111-~111: To join two clauses or introduce examples, consider using an em dash.
Context: ...pports the following protocols: - tar - Tar files, potentially compressed (tar.g...

(DASH_RULE)

---

[typographical] ~112-~112: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpressed (tar.gz, tar.bz2, etc.) - zip - Zip files - http - HTTP URLs - https...

(DASH_RULE)

---

[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ....bz2, etc.) - zip - Zip files - http - HTTP URLs - https - HTTPS URLs - git...

(DASH_RULE)

---

[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...Zip files - http - HTTP URLs - https - HTTPS URLs - git - Git repositories, w...

(DASH_RULE)

---

[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...HTTP URLs - https - HTTPS URLs - git - Git repositories, which can be accessed ...

(DASH_RULE)

---

[typographical] ~116-~116: To join two clauses or introduce examples, consider using an em dash.
Context: ... can be accessed via HTTPS or SSH - hg - Mercurial repositories, accessed via HTT...

(DASH_RULE)

---

[typographical] ~117-~117: To join two clauses or introduce examples, consider using an em dash.
Context: ...ories, accessed via HTTP/S or SSH - s3 - Amazon S3 bucket URLs - gcs - Google C...

(DASH_RULE)

---

[typographical] ~118-~118: To join two clauses or introduce examples, consider using an em dash.
Context: ...H - s3 - Amazon S3 bucket URLs - gcs - Google Cloud Storage URLs - oci - Open...

(DASH_RULE)

---

[typographical] ~119-~119: To join two clauses or introduce examples, consider using an em dash.
Context: ...gcs- Google Cloud Storage URLs -oci` - Open Container Initiative (OCI) images -...

(DASH_RULE)

---

[typographical] ~120-~120: To join two clauses or introduce examples, consider using an em dash.
Context: ...ontainer Initiative (OCI) images - scp - Secure Copy Protocol for SSH-based trans...

(DASH_RULE)

---

[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...rotocol for SSH-based transfers - sftp - SSH File Transfer Protocol :::tip You c...

(DASH_RULE)

---

[style] ~125-~125: Using many exclamation marks might seem excessive (in this case: 8 exclamation marks for a text that’s 3723 characters long)
Context: ... templates first, and then executes the !include function, allowing you to provi...

(EN_EXCESSIVE_EXCLAMATION)

⏰ Context from checks skipped due to timeout of 90000ms (5)

• GitHub Check: Build (windows-latest, windows)
• GitHub Check: Build (ubuntu-latest, linux)
• GitHub Check: website-deploy-preview
• GitHub Check: Analyze (go)
• GitHub Check: Summary

🔇 Additional comments (7)

website/docs/core-concepts/stacks/yaml-functions/env.mdx (2)

31-39: Well-structured arguments section!

The arguments section clearly defines both required and optional parameters with appropriate descriptions.

---

49-59: Excellent examples with security-conscious implementation!

The examples effectively demonstrate the function's usage while maintaining security by avoiding environment variable evaluation.

website/docs/core-concepts/stacks/yaml-functions/include.mdx (5)

43-76: Comprehensive examples covering all major use cases!

The examples effectively demonstrate:

• Local and remote file inclusion
• Various file formats (YAML, JSON, HCL, Markdown)
• YQ expressions for filtering

---

78-100: Excellent technical explanation!

The description effectively explains the function's purpose, limitations it addresses, and technical capabilities.

---

111-121: Add protocol-specific security documentation.

For each supported protocol, consider documenting:

• Authentication requirements
• SSL/TLS configurations
• Network security implications
• Rate limiting considerations

🧰 Tools

🪛 LanguageTool

[typographical] ~111-~111: To join two clauses or introduce examples, consider using an em dash.
Context: ...pports the following protocols: - tar - Tar files, potentially compressed (tar.g...

(DASH_RULE)

---

[typographical] ~112-~112: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpressed (tar.gz, tar.bz2, etc.) - zip - Zip files - http - HTTP URLs - https...

(DASH_RULE)

---

[typographical] ~113-~113: To join two clauses or introduce examples, consider using an em dash.
Context: ....bz2, etc.) - zip - Zip files - http - HTTP URLs - https - HTTPS URLs - git...

(DASH_RULE)

---

[typographical] ~114-~114: To join two clauses or introduce examples, consider using an em dash.
Context: ...Zip files - http - HTTP URLs - https - HTTPS URLs - git - Git repositories, w...

(DASH_RULE)

---

[typographical] ~115-~115: To join two clauses or introduce examples, consider using an em dash.
Context: ...HTTP URLs - https - HTTPS URLs - git - Git repositories, which can be accessed ...

(DASH_RULE)

---

[typographical] ~116-~116: To join two clauses or introduce examples, consider using an em dash.
Context: ... can be accessed via HTTPS or SSH - hg - Mercurial repositories, accessed via HTT...

(DASH_RULE)

---

[typographical] ~117-~117: To join two clauses or introduce examples, consider using an em dash.
Context: ...ories, accessed via HTTP/S or SSH - s3 - Amazon S3 bucket URLs - gcs - Google C...

(DASH_RULE)

---

[typographical] ~118-~118: To join two clauses or introduce examples, consider using an em dash.
Context: ...H - s3 - Amazon S3 bucket URLs - gcs - Google Cloud Storage URLs - oci - Open...

(DASH_RULE)

---

[typographical] ~119-~119: To join two clauses or introduce examples, consider using an em dash.
Context: ...gcs- Google Cloud Storage URLs -oci` - Open Container Initiative (OCI) images -...

(DASH_RULE)

---

[typographical] ~120-~120: To join two clauses or introduce examples, consider using an em dash.
Context: ...ontainer Initiative (OCI) images - scp - Secure Copy Protocol for SSH-based trans...

(DASH_RULE)

---

[typographical] ~121-~121: To join two clauses or introduce examples, consider using an em dash.
Context: ...rotocol for SSH-based transfers - sftp - SSH File Transfer Protocol :::tip You c...

(DASH_RULE)

---

129-152: Well-documented YQ expressions with practical examples!

The section effectively demonstrates YQ usage with clear examples and helpful references.

---

153-172: Excellent cross-platform documentation!

The section effectively covers file path handling across different operating systems with clear examples.

[github-actions]

These changes were released in v1.153.0.