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. For example:

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

Specify either tag or digest; omitting both selects the latest tag. //subdir selectors are supported. Authentication covers static credentials via the interim TG_TMP_OCI_* environment variables and read-only ambient discovery of Docker and containers auth files, following the containers-auth search order OpenTofu uses. Static credentials can be limited to one registry with TG_TMP_OCI_REGISTRY; other registries then fall back to ambient discovery. Without it, the static credentials may be offered to any registry the process contacts, so scope them or avoid setting them when talking to unrelated or untrusted registries. Credential helpers configured in the Docker config (credHelpers and credsStore, such as ecr-login) are invoked when configured and 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 (static credentials, ambient Docker config, or a credential helper such as ecr-login).
• 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.
• Static 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 against a real registry, gated behind a build tag.
• Community feedback on real-world usage.