Skip to content

docs(ce): add community example for github state storage #2568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kvokka wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

docs(ce): add community example for github state storage #2568

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion docs/ce/howto/backendless-mode.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,4 +54,53 @@ create a small resource in your cloud account to store which PR locked which pro

In case of AWS, during the first run digger will create this resource for you. However in case of GCP and azure you need to create it yourself and supply it as an argument.

After the resource is created digger will continue to use it for subsequent runs in order to store information about the locks and function correctly.
After the resource is created digger will continue to use it for subsequent runs in order to store information about the locks and function correctly.

# Community Example: GitHub-Only State Storage

For teams who want to eliminate cloud storage dependencies entirely, there's a community example that demonstrates storing OpenTofu state in GitHub Container Registry (GHCR) using OCI artifacts.

<Note>
This approach is **experimental** and not recommended for production use. It showcases what's possible with the upcoming native OCI backend support in OpenTofu.
</Note>

## What It Does

The [opentaco-with-github-storage-example](https://github.com/kvokka/opentaco-with-github-storage-example) repository demonstrates a fully GitHub-contained infrastructure workflow:

- **State storage**: OpenTofu state stored as encrypted OCI artifacts in GHCR
- **CI/CD**: GitHub Actions with Digger in backendless mode (`no-backend: true`)
- **Everything in one place**: Code, state, and CI all within GitHub's ecosystem

## How It Works

```
PR opened ──> Digger ──> ghoten ──> ORAS push/pull ──> GHCR (encrypted state)
```

The setup uses [ghoten](https://github.com/vmvarela/ghoten), a bridge tool that enables OpenTofu to use ORAS (OCI Registry as Storage) for state management. State files are encrypted using PBKDF2/AES-GCM before being stored in GHCR.

## Benefits

- **No cloud storage setup**: No need for DynamoDB, S3, GCS, or Azure Storage Tables
- **Single platform**: Everything stays within GitHub (repository, packages, actions)
- **Encrypted state**: State and plan files are encrypted at rest
- **GitOps workflow**: PRs trigger plans, comments trigger applies

## Limitations

| Limitation | Impact |
|------------|--------|
| Best-effort locking | No DynamoDB/GCS-style locking. Concurrent applies may corrupt state. |
| Experimental | `ghoten` is archived and pinned to OpenTofu v1.11.4. |
| No key rotation | Encryption key cannot be rotated without state migration. |
| Unrecoverable state | Losing your encryption key means losing your state. |

## When to Consider This

This approach may be useful for:
- Personal projects and experiments
- Learning and demonstrations
- Teams exploring what's possible before native OCI backend support arrives

For production workloads, continue using the standard cloud provider backends (DynamoDB, GCS Bucket, Azure Storage Tables) as described in this guide.