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
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.

settings.inject_github_token

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

When enabled, Atmos automatically injects authentication credentials from ATMOS_GITHUB_TOKEN or GITHUB_TOKEN environment variables.

Set to false to disable automatic GitHub token injection.

settings.inject_gitlab_token

Enables automatic GitLab token injection when vendoring from private GitLab repositories. Defaults to false.

When enabled, Atmos automatically injects authentication credentials from ATMOS_GITLAB_TOKEN or GITLAB_TOKEN environment variables.

settings:
  inject_gitlab_token: true

settings.inject_bitbucket_token

Enables automatic Bitbucket token injection when vendoring from private Bitbucket repositories. Defaults to false.

When enabled, Atmos automatically injects authentication credentials from ATMOS_BITBUCKET_TOKEN or BITBUCKET_TOKEN environment variables.

settings:
  inject_bitbucket_token: true

For Bitbucket, you can also configure a custom username via bitbucket_username setting. If not specified, defaults to x-token-auth.

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.

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.

ATMOS_GITHUB_TOKEN

GitHub token for private repository access.

ATMOS_GITHUB_USERNAME

GitHub username for GHCR authentication.

ATMOS_GITLAB_TOKEN

GitLab token for private repository access.

ATMOS_BITBUCKET_TOKEN

Bitbucket token for private repository access.

ATMOS_BITBUCKET_USERNAME

Bitbucket username for authentication.

See Also

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