Skip to main content

Vendor Configuration

The vendor section in atmos.yaml configures how Atmos discovers and processes vendor manifest files for dependency management.

Configuration​

atmos.yaml
vendor:
  # Path to vendor manifest file or directory
  base_path: vendor.yaml

  # Concurrent downloads and update checks (edition-aware default)
  max_concurrency: 4

  # Configure output format for vendor list command
  list:
    format: table
    columns:
      - name: Component
        value: "{{ .component }}"
      - name: Version
        value: "{{ .version }}"
      - name: Source
        value: "{{ .source }}"

  # Global retry configuration for vendor operations (optional)
  retry:
    max_attempts: 3
    initial_delay: 2s
    max_delay: 30s
    backoff_strategy: exponential

  # Path to the vendor lock file (optional)
  lock_file: vendor.lock.yaml

  # How `atmos vendor pull` reacts to vendor.lock.yaml drift (optional)
  lock:
    enforcement: warn

Configuration Reference​

base_path

Path to the vendor manifest file or directory containing vendor files. Can be a single vendor.yaml file or a directory containing multiple .yaml files.

When a directory is specified, all .yaml files in the directory are processed in lexicographical order.

Default: vendor.yaml

Examples:

  • vendor.yaml - Single manifest file
  • ./vendor.yaml - Explicit relative path
  • vendor/ - Directory containing multiple manifests
list.format

Output format for the atmos vendor list command.

Valid values: table, json, csv Default: table

list.columns

Custom column definitions for table output. Each column has a name (header) and value (Go template expression).

Available template variables:

  • {{ .component }} - Component name
  • {{ .source }} - Source URL
  • {{ .version }} - Version tag
  • {{ .targets }} - Target paths
  • {{ .tags }} - Associated tags
retry

Global retry configuration for vendor operations. These settings apply to all vendor sources unless overridden at the source level.

Retry is useful for handling transient network errors, rate limiting, and other temporary failures when downloading from remote repositories.

retry.max_attempts
Maximum number of retry attempts. Default: 3
retry.initial_delay
Initial delay before the first retry. Default: 2s
retry.max_delay
Maximum delay between retries. Default: 30s
retry.backoff_strategy
Strategy for increasing delay between retries. Values: exponential, linear, constant. Default: exponential
retry.multiplier
Multiplier for exponential backoff. Default: 2.0
retry.random_jitter
Random jitter factor (0.0-1.0) to add randomness to delays. Default: 0.1
retry.max_elapsed_time
Maximum total time for all retry attempts. Default: 5m
lock_file

The vendor lock file. It records a per-file SHA-256 receipt for every artifact vendored through vendor.yaml or component.yaml. The atmos vendor verify command checks this file for drift; atmos vendor pull and atmos vendor update --pull write to it.

Default: vendor.lock.yaml

lock.enforcement

How atmos vendor pull reacts when a package's on-disk state no longer matches its vendor.lock.yaml receipt.

When the receipt matches the declaration and all its recorded files are absent, Atmos treats the package as uninstalled and reinstalls it without a drift warning, including under strict. This supports vendor clean followed by vendor pull. Partially missing or modified files and changed declarations still use the enforcement policy below.

Valid values:

  • warn — re-fetch the drifted package and print one warning per package naming why it drifted.
  • silent — re-fetch the drifted package with no reporting.
  • strict — refuse to run (before any fetch/copy/write) when a drifted package is found and --refresh-lock was not explicitly passed, naming every drifted package and its reason.

Default: warn

Override per invocation with --lock-enforcement <strict|warn|silent> on atmos vendor pull or atmos vendor update --pull.

Concurrency​

vendor.max_concurrency sets the maximum number of simultaneous downloads and preparation jobs for vendor pull, and upstream checks for vendor update. The pull phase of vendor update --pull uses the same value.

Precedence is explicit --max-concurrency flag → ATMOS_VENDOR_MAX_CONCURRENCY environment variable → merged configuration → edition-aware default. Values must be positive integers; explicit zero, negative, and malformed values fail before vendoring begins.

Edition pinDefault workers
Unpinned4
Before 2026-09-151
On or after 2026-09-154

An explicit value overrides the edition pin. Partial dates follow the existing edition rules: "2026-08" ends on August 31 and keeps one worker; "2026-09" includes the September change and uses four.

atmos vendor pull --max-concurrency 8
ATMOS_VENDOR_MAX_CONCURRENCY=2 atmos vendor update --check
atmos vendor update --pull --max-concurrency 4

Downloads and preparation overlap. Destination copying and lock receipt updates follow declaration order, including component sources before their mixins. Local sources are staged after preceding writes, so they observe those files. At most twice the worker count may be downloading or waiting to be installed. One worker preserves serial execution.

All editions receive the progress display. Active rows show the current phase, with byte counts when the download backend provides them. A ready package is waiting for its turn to install; success appears only after files and receipts are written. Completed results remain visible. CI and redirected output use plain result lines on stderr, leaving structured update output on stdout intact.

Concurrent vendoring operations coordinate destination writes and receipts with advisory locks. A failed package does not undo packages already installed. On interruption, Atmos cancels pending work, cleans temporary downloads, and lets an already-started materialization finish before releasing its locks.

Component Updater Configuration​

The vendor.update and vendor.ci sections configure atmos vendor update --pull-request — see Native Pull Requests for Vendored Component Updates for the full workflow and a worked example.

atmos.yaml
vendor:
  update:
    execution:
      mode: current # or "worktree"
    batching:
      mode: scope # the only supported value today
    groups:
      platform:
        include: ["terraform/vpc", "terraform/eks/*"]
        exclude: ["terraform/eks/legacy"]
  ci:
    pull_request:
      provider: github
      base_branch: main
      branch_prefix: atmos/component-updater
      title: "chore(components): update {{ .scope.name }}"
      # body left unset here to use the default: the Atmos CI badge, a one-line explanation, and
      # {{ .updates | markdownTable }} -- set your own template to replace it entirely.
      labels: [component-update]
      draft: false
      reviewers: []
      assignees: []
    summary:
      enabled: true
update.execution.mode

The default, current, runs the whole cycle — discover, branch, commit, push — in the invoking checkout. The worktree mode runs it in an isolated linked Git worktree instead. The invoking checkout stays untouched, which helps when other steps in the same job need an unmodified checkout.

update.batching.mode
The only supported value is scope: one branch and one PR for the whole update run. Per-component batching (one PR per updated component) isn't implemented yet.
update.groups.<name>

Selects components for --group <name>. Each group has include and optional exclude glob lists against component paths; exclusions win.

ci.pull_request.provider
Pull request provider. Valid values: github, azuredevops. Default: github.
ci.pull_request.base_branch
Base branch for the pull request. Default: the remote's advertised default branch.
ci.pull_request.branch_prefix
Prefix for the deterministic branch name. Default: atmos/component-updater.
ci.pull_request.title / ci.pull_request.body

Go templates rendered with .scope.name and .updates (see markdownTable in the example above). Title default: "chore(components): update {{ .scope.name }}". Body default: the Atmos CI badge, a one-line "Automated by atmos vendor update --pull-request" note, and {{ .updates | markdownTable }} — not just the bare table on its own.

ci.pull_request.labels / .reviewers / .assignees

Atmos applies these additively on every reconciliation. Default label: [component-update]. Azure DevOps pull requests have no assignee concept — setting assignees with provider: azuredevops fails with an error instead of silently dropping it; use reviewers there instead. With provider: azuredevops, each reviewers entry is a display name, account name, or email — Atmos resolves it to the individual it identifies. Only individuals are supported today, not groups.

ci.pull_request.draft
Create the pull request as a draft. Default: false.
ci.pull_request.organization / .project / .repository

Required when provider: azuredevops. Azure DevOps addresses a repository with three segments — organization, project, and repository — instead of GitHub's owner/repository pair derived from the Git remote.

ci.summary.enabled
Whether to write a GitHub Actions step summary. Default: true.
note

A default GITHUB_TOKEN won't trigger downstream on: pull_request/on: push Actions workflows. Pair the Component Updater with the github/sts auth integration to get a token that does. See atmos vendor update's token precedence notes for details.

note

The azuredevops provider authenticates with a personal access token in the AZURE_DEVOPS_EXT_PAT environment variable, used as HTTP Basic auth with an empty username. The token needs Code (Read & Write) permission on the target project.

vendor:
  ci:
    pull_request:
      provider: azuredevops
      organization: my-org
      project: my-project
      repository: my-repo

Vendor Manifest Structure​

The vendor manifest file defines external dependencies to pull into your project:

vendor.yaml
apiVersion: atmos/v1
kind: AtmosVendorConfig
metadata:
  name: my-project-vendor
  description: Vendor dependencies for my project
spec:
  imports:
    - vendor/common.yaml
  sources:
    - component: vpc
      source: github.com/cloudposse/terraform-aws-vpc.git//src?ref={{.Version}}
      version: 1.0.0
      targets:
        - components/terraform/vpc

    - component: eks
      source: github.com/cloudposse/terraform-aws-eks-cluster.git?ref={{.Version}}
      version: 2.0.0
      targets:
        - components/terraform/eks
      included_paths:
        - "**/*.tf"
      excluded_paths:
        - "examples/**"

Multiple Manifest Files​

You can organize vendor configurations across multiple files:

vendor/
├── aws.yaml        # AWS-related components
├── kubernetes.yaml # Kubernetes components
└── common.yaml     # Shared dependencies
atmos.yaml
vendor:
  base_path: vendor/

Atmos processes files in alphabetical order: aws.yaml, then common.yaml, then kubernetes.yaml.

Related Commands​

Try It​

Explore a working example that demonstrates vendor configuration.

demo-vendoringView full example
atmos vendor pull
00:00.0 / 00:00.0

Example: Demo Vendoring

Pull Terraform modules from GitHub, S3, or OCI registries with pinned versions.

Learn more about Vendoring.

What You'll See

  • Vendor manifest defining component sources
  • Multiple vendor sources from GitHub
  • Version pinning with ref parameter
  • Modular vendor configs in vendor.d/

Try It

cd examples/demo-vendoring

# List available vendor sources
atmos vendor list

# Pull all vendored components
atmos vendor pull

# Pull a specific component
atmos vendor pull --component=weather

Key Files

FilePurpose
vendor.yamlMain vendor manifest with component sources
vendor.d/Modular vendor configurations
vendor/Downloaded components (after atmos vendor pull)
Browse all files

Related​