ghoten

Ghoten

Name origin: Ghoten blends GhitHub and OpenTofu, with a nod to Goten from Dragon Ball Z.

An OpenTofu fork with a native ORAS backend for OCI registry state storage.

Ghoten adds a first-class oras backend that speaks the OCI distribution protocol directly. Use an OCI-compatible registry — such as GitHub Container Registry (GHCR) — as the durable store for your infrastructure state, without external HTTP backends or third-party wrappers.

Upstream: Ghoten tracks OpenTofu and carries only the additions required for the ORAS backend. All standard OpenTofu functionality is preserved.

Key Features

• Native OCI storage — State, locks, and versions stored as OCI artifacts via ORAS
• Atomic locking — Generation semantics prevent concurrent lock holders
• Stale lock cleanup (TTL) — Crashed-process locks auto-cleared on next acquisition
• State versioning — Historical snapshots with async background retention cleanup
• Gzip compression — Optional state compression before pushing
• Rate limiting & retry — Token-bucket limiter + exponential backoff for transient errors
• GHCR deletion fallback — Falls back to GitHub Packages API when OCI DELETE returns 405
• Docker credential helpers — Reuses Docker config with caching and singleflight deduplication
• OpenTelemetry tracing — All OCI HTTP calls instrumented via otelhttp
• Client-side encryption — Combine with OpenTofu state encryption

Installation

# Build from source
git clone https://github.com/vmvarela/ghoten.git && cd ghoten
make build

# Or pull Docker images
docker pull ghcr.io/vmvarela/ghoten:<version>          # Alpine (git/bash/openssh)
docker pull ghcr.io/vmvarela/ghoten:<version>-minimal   # Scratch (binary only)

Pre-built binaries for 17 platform combinations are available on the Releases page.

GitHub Action

Run Ghoten in your workflows with zero configuration — the action installs the binary, authenticates to GHCR, initializes the ORAS backend, and runs your command with PR comments and Job Summaries out of the box.

Your HCL only needs an empty backend block — the action injects repository, compression, lock_ttl, and max_versions automatically:

terraform {
  backend "oras" {}
}

Quick Start

on: pull_request

jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: vmvarela/ghoten@v1

The action will install Ghoten, authenticate to GHCR, init with the ORAS backend (ghcr.io/<owner>/tf-state.<repo>), run ghoten plan, post a PR comment, and generate a Job Summary.

Plan on PR, Apply on Merge

name: Infrastructure
on:
  pull_request:
  push:
    branches: [main]

jobs:
  plan:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    permissions: { contents: read, packages: write, pull-requests: write }
    steps:
      - uses: actions/checkout@v6
      - uses: vmvarela/ghoten@v1

  apply:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions: { contents: read, packages: write }
    steps:
      - uses: actions/checkout@v6
      - uses: vmvarela/ghoten@v1
        with:
          command: apply

Inputs

Outputs

More Examples

# Format check
- uses: vmvarela/ghoten@v1
  with: { command: fmt, fmt-check: true }

# With variables
- uses: vmvarela/ghoten@v1
  with:
    command: plan
    var-file: prod.tfvars
    variables: |
      region=eu-west-1
      environment=production

# Custom backend repository
- uses: vmvarela/ghoten@v1
  with:
    command: plan
    backend-repository: ghcr.io/myorg/custom-state-repo

# Plan → Apply in same job
- uses: vmvarela/ghoten@v1
  id: plan
  with: { command: plan }
- uses: vmvarela/ghoten@v1
  if: steps.plan.outputs.plan-has-changes == 'true'
  with: { command: apply }

Permissions

packages: write covers version retention cleanup. The separate delete:packages permission is only needed to delete entire packages from GHCR.

ORAS Backend

Configuration

Usage Examples

With the GitHub Action — just declare an empty backend; the action provides everything via env vars and -backend-config:

terraform {
  backend "oras" {}
}

Standalone — minimal:

terraform {
  backend "oras" {
    repository = "ghcr.io/acme/infra-state"
  }
}

Standalone — production-ready:

terraform {
  backend "oras" {
    repository   = "ghcr.io/myorg/infra-state"
    compression  = "gzip"
    lock_ttl     = 300
    max_versions = 10
  }

  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 }
    plan  { method = method.aes_gcm.main }
  }
}

Tip: For production, prefer a KMS-backed key provider (AWS KMS, GCP KMS, etc.) over PBKDF2.

Authentication

Credentials are discovered in order:

1. Docker credential helpers — Docker config / credential store (cached, singleflight-deduplicated)
2. CLI host credentials — OpenTofu/Terraform login tokens (ghoten login)

How State Is Stored

Tags act as stable references inside the OCI repository:

If the workspace name is not a valid OCI tag, a ws-<sha256> form is used instead, with the real name persisted in OCI annotations.

Security

• Enable client-side encryption — encrypts state before it leaves your machine
• Keep the repository private with least-privilege tokens
• Prefer registries with encryption at rest and audit trails

Note: Primarily tested against GHCR. Other OCI registries should work but are not yet validated.

Testing

go test ./...                                        # Full suite
go test ./internal/backend/remote-state/oras/...     # ORAS backend (in-memory fake registry)

Troubleshooting

Contributing

• GitHub Issues · Contributing Guide · Code of Conduct
• For upstream questions: OpenTofu Discussions

Security

Report vulnerabilities via GitHub Security Advisories. See SECURITY.md.

License

Mozilla Public License 2.0