OpenTofu ORAS Backend: Store State in GitHub Container Registry (GHCR)

Source: Dev.to

Introduction

OpenTofu 1.10 added OCI support for providers, but it left state storage unanswered.
For many projects, a 153 MB tfstate in S3 + DynamoDB for locking is overkill, especially when the team already uses:

• An OCI registry (e.g., GHCR)
• GitHub Actions to deploy Terraform code

The fork below provides a native ORAS backend that stores state as OCI artifacts (content‑addressable).

ORAS Backend Configuration

terraform {
  backend "oras" {
    repository  = "ghcr.io/org/project-state"
    compression = "gzip"

    versioning {
      enabled      = true
      max_versions = 5
    }
  }
}

Encryption (optional)

terraform {
  backend "oras" {
    repository = "ghcr.io/my-org/tf-state"
  }

  encryption {
    key_provider "pbkdf2" "main" {
      passphrase = var.state_passphrase
    }
    method "aes_gcm" "main" {
      key_provider = key_provider.pbkdf2.main
    }
    state {
      method = method.aes_gcm.main
    }
  }
}

Installation

# Installs as `tofu-oras`
curl -sSL https://raw.githubusercontent.com/vmvarela/opentofu/develop/install.sh | sh

Building from Source

git clone https://github.com/vmvarela/opentofu
cd opentofu
go build -o tofu-oras ./cmd/tofu

Full Documentation

See the ORAS Backend README for detailed usage instructions.

Use Cases

• Startups with lean infra‑as‑code
• Personal or side projects (free GHCR tier)
• Air‑gapped environments using a registry mirror
• Teams already invested in the OCI ecosystem
• Multi‑cloud projects

Future Plans (if community interest grows)

• Improve test coverage
• Add more examples for different scenarios
• Test with OCI registries other than GHCR

Community Feedback

What do you think? Would you store state in OCI registries instead of S3? Which features would you need to adopt this approach?

Repository: (branch/tag v1.11.2-oras, etc.)