# 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

**File:** `atmos.yaml`

```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](/cli/configuration/settings/experimental) | Control experimental feature behavior |
| [Terminal](/cli/configuration/settings/terminal) | Terminal display, color, width, pager, and syntax highlighting |
| [Secret Masking](/cli/configuration/settings/mask) | Automatic secret detection and masking in output |
| [Markdown Styling](/cli/configuration/settings/markdown-styling) | Customize markdown rendering in terminal |
| [Atmos Pro](/cli/configuration/settings/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:**
  ```yaml
  settings:
    github_username: "myusername"
  ```
  **GitHub Actions usage:**
  ```yaml
  # 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)**

  :::warning 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](/cli/configuration) — Overview of CLI configuration
- [Environment Variables](/cli/environment-variables) — All configuration environment variables