---
name: oci
since: "1.1.1"
---

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:

```hcl
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](https://docs.docker.com/reference/cli/docker/login/#credential-helpers)
configured in the Docker config
([`credHelpers`](https://docs.docker.com/reference/cli/docker/login/#credential-helpers)
and
[`credsStore`](https://docs.docker.com/reference/cli/docker/login/#credential-stores),
such as
[`ecr-login`](https://github.com/awslabs/amazon-ecr-credential-helper))
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

```bash
# 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](https://github.com/gruntwork-io/terragrunt/issues/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:

- [x] A getter that resolves `oci://` sources, selecting the `application/vnd.opentofu.modulepkg` artifact and its `archive/zip` layer, with blob digest verification.
- [x] Static and ambient Docker-config credential discovery matching OpenTofu's search order.
- [x] 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.
