Skip to main content

Vendor URL Syntax

Atmos vendor sources support a wide variety of URL schemes and path formats for pulling external components, stacks, and configurations. Understanding the URL syntax helps you effectively vendor dependencies from any source.

URL Schemes​

Atmos vendoring is built on HashiCorp's go-getter library, with additional support for OCI registries and smart defaults for Git hosting platforms.

Supported Schemes​

SchemeDescriptionExample
(no scheme)Implicit HTTPS for Git hostsgithub.com/owner/repo.git?ref=v1.0
https://HTTPS protocolhttps://github.com/owner/repo.git//path?ref=v1.0
git::Explicit Git protocolgit::https://github.com/owner/repo.git?ref=v1.0
oci://OCI registries (Atmos extension)oci://ghcr.io/owner/image:tag
file://Local filesystemfile:///absolute/path/to/components
ssh://SSH protocolssh://git@github.com/owner/repo.git
SCP-styleSSH shorthandgit@github.com:owner/repo.git
tip

Most of the time, you can use the simplest form without an explicit scheme. Atmos will automatically detect the right protocol.

Subdirectory Syntax​

One of the most powerful features is the subdirectory delimiter that lets you vendor only a specific directory from a repository.

The Double-Slash Delimiter​

The double-slash (//) is a special delimiter (not a path separator) that separates:

  1. Left side: The source to download (repository URL, archive, etc.)
  2. Right side: The subdirectory within that source to extract
source: "github.com/cloudposse-terraform-components/aws-vpc.git//modules/public-subnets?ref=1.398.0"

Result: Clones the repository and extracts only the modules/public-subnets subdirectory.

Common Patterns​

PatternWhat It MeansWhen To Use
repo.git//path/to/dirExtract path/to/dir subdirectoryWhen you only need a specific directory
repo.git//.Extract root directoryWhen you need the entire repository
repo.gitNo subdirectory specifiedAtmos adds //. automatically for Git URLs
Deprecated: Triple-Slash Pattern

The triple-slash pattern (///) was used in older Atmos versions to indicate the root directory:

# Old syntax (still works but deprecated)
source: "github.com/owner/repo.git///?ref=v1.0"

# New syntax (explicit and clear)
source: "github.com/owner/repo.git//.?ref=v1.0"

Atmos automatically normalizes the triple-slash pattern for backward compatibility, but we recommend using //. for clarity.

Query Parameters​

Query parameters are appended to the URL and control how the source is downloaded.

Common Parameters​

ParameterDescriptionExample
ref=<value>Git reference (branch, tag, commit)?ref=main or ?ref=v1.0.0
depth=<n>Git clone depth (shallow clone)?depth=1
sshkey=<path>Path to SSH private key?sshkey=~/.ssh/id_rsa
Automatic Shallow Clones

Atmos automatically adds depth=1 to Git clones for faster downloads. You can override this by explicitly setting depth.

Examples​

source: "github.com/cloudposse-terraform-components/aws-vpc.git?ref=v1.398.0"

URL Patterns by Platform​

Implicit HTTPS (recommended)​

# Simple - implicit HTTPS, root directory
source: "github.com/cloudposse-terraform-components/aws-vpc.git?ref=v1.398.0"

With Subdirectory​

# Clone and extract specific subdirectory
source: "github.com/cloudposse-terraform-components/aws-vpc.git//modules/public-subnets?ref=v1.398.0"

Explicit git:: Protocol​

# Explicit git protocol
source: "git::https://github.com/cloudposse/atmos.git//examples?ref=main"

SSH Authentication​

# SSH protocol (requires SSH key setup)
source: "git::ssh://git@github.com/cloudposse-terraform-components/aws-vpc.git?ref=v1.0.0"

# Or SCP-style shorthand
source: "git@github.com:cloudposse-terraform-components/aws-vpc.git?ref=v1.0.0"

With Credentials (Not Recommended)​

# HTTPS with embedded credentials (not recommended, use tokens)
source: "https://user:password@github.com/owner/repo.git?ref=v1.0"
Token Authentication

Atmos automatically injects GitHub tokens from ATMOS_GITHUB_TOKEN or GITHUB_TOKEN environment variables. No need to embed credentials in URLs!

Local Paths​

Relative Paths​

# Relative to vendor.yaml location
source: "../../../components/terraform/mixins"

Absolute Paths​

# Absolute filesystem path
source: "/absolute/path/to/components"

file:// URI​

# file:// URI (gets converted to absolute path)
source: "file:///path/to/local/components"
Path Traversal Security

Atmos validates local paths to prevent directory traversal attacks. Paths with .. are carefully validated.

HTTP/HTTPS Downloads​

Archive Files​

# Download and extract archives
source: "https://example.com/components.tar.gz"
source: "https://example.com/components.zip"

Single Files​

# Download a single file
source: "https://raw.githubusercontent.com/cloudposse/terraform-null-label/0.25.0/exports/context.tf"

Template Variables​

Atmos supports Go templates in vendor URLs for dynamic configuration.

Available Variables​

VariableDescriptionExample
{{.Component}}Component nameReplaced with the value of component: field
{{.Version}}Component versionReplaced with the value of version: field

Example​

sources:
  - component: "vpc"
    source: "github.com/cloudposse-terraform-components/aws-{{.Component}}.git?ref={{.Version}}"
    version: "1.398.0"
    targets:
      - "components/terraform/{{.Component}}"

Result: Downloads from aws-vpc repository at version 1.398.0 to components/terraform/vpc.

Authentication​

Credential Precedence Order​

Atmos uses the following precedence order for credentials when accessing Git repositories:

  1. User-specified credentials in URL (highest precedence) - If you specify credentials directly in the source URL, they are always used
  2. Automatic token injection - If no credentials are in the URL, Atmos injects tokens from environment variables
  3. No authentication - If no credentials are provided and no tokens are available
User Credentials Always Win

If your source URL includes credentials (e.g., https://myuser:mytoken@github.com/repo.git), Atmos will never overwrite them with automatic token injection. This allows you to use specific credentials per repository when needed.

Automatic Token Injection​

Atmos automatically injects tokens for supported platforms when no user credentials are in the URL:

PlatformEnvironment VariablesUsernameEnabled by Default
GitHubATMOS_GITHUB_TOKEN or GITHUB_TOKENx-access-token✅ Yes
GitLabATMOS_GITLAB_TOKEN or GITLAB_TOKENoauth2❌ No
BitbucketATMOS_BITBUCKET_TOKEN or BITBUCKET_TOKENx-token-auth❌ No

Token Resolution: For each platform, Atmos first tries the ATMOS_* prefixed token, then falls back to the standard token if not set.

Configuration in atmos.yaml:

GitHub token injection is enabled by default. To disable it:

settings:
  inject_github_token: false

To enable GitLab or Bitbucket token injection:

settings:
  inject_gitlab_token: true
  inject_bitbucket_token: true

See the CLI Configuration documentation for more details on these settings.

SSH Keys​

For SSH-based Git access:

# SSH with default key (~/.ssh/id_rsa)
source: "git@github.com:owner/private-repo.git?ref=main"

# SSH with custom key
source: "git@github.com:owner/private-repo.git?ref=main&sshkey=~/.ssh/custom_key"

Embedded Credentials​

# Not recommended: credentials in URL
source: "https://username:password@github.com/owner/repo.git?ref=v1.0"
Security Warning

Embedding credentials in URLs is not recommended. Use environment variables for tokens or SSH keys instead.

Best Practices​

1. Use Explicit Versions​

# Pin to specific version
source: "github.com/cloudposse-terraform-components/aws-vpc.git?ref=v1.398.0"

2. Use Subdirectories When Needed​

# ✅ Extract specific subdirectory from a repository
source: "github.com/cloudposse-terraform-components/aws-vpc.git//modules/public-subnets?ref=v1.398.0"

# ✅ Use root directory (no subdirectory needed)
source: "github.com/cloudposse-terraform-components/aws-vpc.git?ref=v1.398.0"

3. Use Token Authentication​

# Set GitHub token
export ATMOS_GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or use standard GitHub token
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Prefer OCI for Binary Artifacts​

# ✅ OCI for container images and binary artifacts
source: "oci://ghcr.io/cloudposse/components/terraform/stable/aws/vpc:v1.0.0"

# ✅ Git for source code
source: "github.com/cloudposse-terraform-components/aws-vpc.git?ref=v1.398.0"

Troubleshooting​

Empty Directories After Vendor Pull​

Symptom: atmos vendor pull creates directories but no files are pulled.

Causes:

  1. Using triple-slash (///) instead of double-slash-dot (//.) for root directory
  2. Incorrect subdirectory path
  3. Files excluded by excluded_paths or included_paths glob patterns

Solution:

# ✅ Correct: Use //. for root
source: "github.com/owner/repo.git//.?ref=v1.0"

# ❌ Avoid: Triple-slash (deprecated)
source: "github.com/owner/repo.git///?ref=v1.0"

Authentication Failures​

Symptom: fatal: Authentication failed or permission denied

Solution:

  1. Verify token is set: echo $ATMOS_GITHUB_TOKEN
  2. Check token has correct permissions (repo access)
  3. For SSH: Verify SSH keys are set up (ssh -T git@github.com)

Rate Limits​

Symptom: API rate limit exceeded

Solution: Set authentication tokens to increase rate limits:

  • GitHub: 60 req/hr (unauthenticated) → 5,000 req/hr (authenticated)
  • GitLab: Similar improvements with tokens
  • Bitbucket: Token required for most operations

Related Documentation​