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

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

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.

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. 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].
ci.pull_request.draft
Create the pull request as a draft. Default: false.
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.

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​