Oci

Experimental support for downloading modules from OCI Distribution registries using oci:// sources.

oci - What it does

OpenTofu 1.10 can download modules from an OCI Distribution registry using an oci:// source. This experiment gates Terragrunt's native support for the same sources, so a single source string works the same way in both tofu and Terragrunt against registries such as Amazon ECR, GitHub Container Registry, Azure Container Registry, Google Artifact Registry, and self-hosted or air-gapped registries.

With the experiment enabled, Terragrunt accepts oci:// source URLs in terraform { source = "..." } blocks, and in the unit and stack blocks of a terragrunt.stack.hcl. For example:

terraform {
  source = "oci://ghcr.io/acme/terraform-modules/vpc?tag=1.0.0"
}

unit "vpc" {
  source = "oci://ghcr.io/acme/terragrunt-units/vpc?tag=1.0.0"
  path   = "vpc"
}

Specify either tag or digest; omitting both selects the latest tag. //subdir selectors are supported.

Credentials come from OpenTofu's CLI config, in the oci_credentials and oci_default_credentials blocks. Terragrunt reads the file named by TF_CLI_CONFIG_FILE or TERRAFORM_CONFIG, otherwise the first of ~/.tofurc and ~/.terraformrc that exists (on Windows, %APPDATA%\tofu.rc and %APPDATA%\terraform.rc). Unless one of those environment variables is set, it also merges the *.tfrc and *.tfrc.json files in OpenTofu's config directory. Terragrunt also reads ambient Docker and containers auth files (~/.docker/config.json and containers auth.json), following the containers-auth search order OpenTofu uses as of OpenTofu 1.12. Set docker_style_config_files in oci_default_credentials to replace those default search paths, or an empty list to disable ambient discovery entirely.

Terragrunt ranks every matching CLI-config and ambient credential together by how much of the repository path each one matches, and uses the single best match. A CLI-config entry wins only when both candidates match equally closely. The oci_default_credentials helper is the global fallback, and Terragrunt pulls anonymously when nothing matches. Set discover_ambient_credentials = false in the oci_default_credentials block to use CLI config only.

Credential helpers configured in either place (credHelpers and credsStore in the Docker config, or a block's docker_credentials_helper, such as ecr-login) are invoked when selected as the credential source, so ECR and other helper-backed registries work without a baked-in login. When the experiment is disabled, oci:// sources remain unsupported.

oci - How to enable it

# Via CLI flag
terragrunt --experiment oci run -- plan

# Via environment variable
export TG_EXPERIMENT=oci
terragrunt run -- plan

oci - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#4555. When reporting issues or providing feedback, please include:

• The registry you are using (ECR, GHCR, ACR, GAR, self-hosted).
• The authentication method (an OpenTofu CLI-config oci_credentials block, ambient Docker config, or a credential helper such as ecr-login), and the CLI config file in use.
• The full oci:// source string, and whether you pin by tag or digest.
• Any errors encountered during module download.

oci - Criteria for stabilization

To transition the oci feature to a stable release, the following must be addressed, at a minimum:

• A getter that resolves oci:// sources, selecting the application/vnd.opentofu.modulepkg artifact and its archive/zip layer, with blob digest verification.
• OpenTofu CLI-config and ambient Docker-config credential discovery matching OpenTofu's search order.
• Credential-helper support (docker-credential-*, ecr-login) so ECR and other helper-backed registries work through the configured helper.
• Content-addressable caching keyed on the resolved manifest digest, with correct re-resolution of mutable tags.
• A portability guarantee that one source string produces an identical module via tofu and Terragrunt.
• Documentation covering the source syntax, authentication tiers, and publishing contract.
• Integration test coverage driving the full download chain against a local OCI Distribution registry.
• Gated CI coverage against hosted registries (GHCR, ECR) with real credentials.
• Community feedback on real-world usage.