Settings

The settings section configures Atmos global settings that affect how stacks are processed, how lists are merged, how output is displayed, and how authentication tokens are injected for private repositories.

Configuration

atmos.yaml

settings:
  # Specifies how lists are merged in Atmos stack manifests
  list_merge_strategy: replace

  # Terminal settings
  terminal:
    max_width: 120
    pager: false
    color: true

  # Token injection settings
  inject_github_token: true
  inject_gitlab_token: false
  inject_bitbucket_token: false
  github_username: ""

Settings Sections

Section	Description
Experimental	Control experimental feature behavior
Terminal	Terminal display, color, width, pager, and syntax highlighting
Secret Masking	Automatic secret detection and masking in output
Markdown Styling	Customize markdown rendering in terminal
Atmos Pro	Atmos Pro integration for stack locking and workspace management

List Merge Strategy

settings.list_merge_strategy

Specifies how lists are merged in Atmos stack manifests. Can also be set using ATMOS_SETTINGS_LIST_MERGE_STRATEGY environment variable or --settings-list-merge-strategy command-line argument.

The following strategies are supported:

replace

Most recent list imported wins (the default behavior).

append

The sequence of lists is appended in the same order as imports.

merge

The items in the destination list are deep-merged with the items in the source list. The items in the source list take precedence. The items are processed starting from the first up to the length of the source list (the remaining items are not processed). If the source and destination lists have the same length, all items in the destination lists are deep-merged with all items in the source list.

Token Injection

Atmos can automatically inject authentication tokens when vendoring from private repositories. This eliminates the need to embed credentials in vendor URLs.

For each VCS provider, two pieces of configuration are involved:

• A boolean inject_<provider>_token flag that turns injection on or off.
• One or more token fields that supply the credential. Atmos prefers the Atmos-specific token (atmos_<provider>_token / ATMOS_<PROVIDER>_TOKEN) and falls back to the standard token (<provider>_token / <PROVIDER>_TOKEN) so Atmos credentials don't collide with those used by Terraform or other tools running in the same shell.

GitHub

settings.inject_github_token

Enables automatic GitHub token injection when vendoring from private GitHub repositories. Defaults to true.

Set to false to disable automatic GitHub token injection.

• Type: boolean
• Default: true
• Environment Variable: ATMOS_INJECT_GITHUB_TOKEN

settings.atmos_github_token

Atmos-specific GitHub token. Tried first when injecting credentials. Use this when you want a dedicated token for Atmos that is independent of GITHUB_TOKEN.

• Type: string
• Environment Variable: ATMOS_GITHUB_TOKEN

settings.github_token

Standard GitHub token, used as a fallback when atmos_github_token is unset.

• Type: string
• Environment Variable: GITHUB_TOKEN

settings.github_username

Specifies the GitHub username for OCI registry authentication to GitHub Container Registry (ghcr.io).

When pulling artifacts from ghcr.io using oci://ghcr.io/... sources, Atmos requires a GitHub username along with the token. The username can be configured via:

• github_username setting in atmos.yaml
• ATMOS_GITHUB_USERNAME environment variable (highest precedence)
• GITHUB_ACTOR environment variable (automatically set in GitHub Actions)
• GITHUB_USERNAME environment variable

Configuration example:

settings:
  github_username: "myusername"

GitHub Actions usage:

# In GitHub Actions, GITHUB_ACTOR is automatically available
# No additional configuration needed
- name: Pull from GHCR
  run: atmos vendor pull -c my-component
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    # GITHUB_ACTOR is automatically set by GitHub Actions

Note: Unlike Git repository authentication (which uses x-access-token as username), GitHub Container Registry requires your actual GitHub username. Without a username, authentication will fail even if ATMOS_GITHUB_TOKEN or GITHUB_TOKEN is set.

GitLab

settings.inject_gitlab_token

Enables automatic GitLab token injection when vendoring from private GitLab repositories.

• Type: boolean
• Default: false
• Environment Variable: ATMOS_INJECT_GITLAB_TOKEN

settings.atmos_gitlab_token

Atmos-specific GitLab token. Tried first when injecting credentials.

• Type: string
• Environment Variable: ATMOS_GITLAB_TOKEN

settings.gitlab_token

Standard GitLab token, used as a fallback when atmos_gitlab_token is unset.

• Type: string
• Environment Variable: GITLAB_TOKEN

Bitbucket

settings.inject_bitbucket_token

Enables automatic Bitbucket token injection when vendoring from private Bitbucket repositories.

• Type: boolean
• Default: false
• Environment Variable: ATMOS_INJECT_BITBUCKET_TOKEN

settings.atmos_bitbucket_token

Atmos-specific Bitbucket token. Tried first when injecting credentials.

• Type: string
• Environment Variable: ATMOS_BITBUCKET_TOKEN

settings.bitbucket_token

Standard Bitbucket token, used as a fallback when atmos_bitbucket_token is unset.

• Type: string
• Environment Variable: BITBUCKET_TOKEN

settings.bitbucket_username

Optional Bitbucket username for token authentication. Defaults to x-token-auth.

• Type: string
• Default: x-token-auth
• Environment Variable: BITBUCKET_USERNAME

Deprecated Settings

settings.docs (Deprecated)

Deprecated

The settings.docs section is deprecated and will be removed in a future version. Please use settings.terminal instead.

max-width (Deprecated)

Use settings.terminal.max_width instead.

pagination (Deprecated)

Use settings.terminal.pager instead.

Environment Variables

ATMOS_SETTINGS_LIST_MERGE_STRATEGY

List merge strategy: replace, append, merge. Maps to settings.list_merge_strategy.

ATMOS_INJECT_GITHUB_TOKEN

Enable or disable automatic GitHub token injection (true/false). Maps to settings.inject_github_token.

ATMOS_GITHUB_TOKEN

Atmos-specific GitHub token. Tried before GITHUB_TOKEN. Maps to settings.atmos_github_token.

GITHUB_TOKEN

Standard GitHub token, used as a fallback. Maps to settings.github_token.

ATMOS_GITHUB_USERNAME

GitHub username for GHCR authentication. Maps to settings.github_username.

ATMOS_INJECT_GITLAB_TOKEN

Enable or disable automatic GitLab token injection (true/false). Maps to settings.inject_gitlab_token.

ATMOS_GITLAB_TOKEN

Atmos-specific GitLab token. Tried before GITLAB_TOKEN. Maps to settings.atmos_gitlab_token.

GITLAB_TOKEN

Standard GitLab token, used as a fallback. Maps to settings.gitlab_token.

ATMOS_INJECT_BITBUCKET_TOKEN

Enable or disable automatic Bitbucket token injection (true/false). Maps to settings.inject_bitbucket_token.

ATMOS_BITBUCKET_TOKEN

Atmos-specific Bitbucket token. Tried before BITBUCKET_TOKEN. Maps to settings.atmos_bitbucket_token.

BITBUCKET_TOKEN

Standard Bitbucket token, used as a fallback. Maps to settings.bitbucket_token.

BITBUCKET_USERNAME

Bitbucket username for authentication. Maps to settings.bitbucket_username.

See Also

• CLI Configuration — Overview of CLI configuration
• Environment Variables — All configuration environment variables