tfconfig

tfconfig is the OpenUdon-owned static Terraform/OpenTofu configuration parser package and tool.

Module path:

github.com/OpenUdon/tfconfig

The target contract is a deterministic tfconfig.static.v1 fact model that OpenUdon can consume when scaffolding reviewable UWS packages from Terraform/OpenTofu configuration and OpenAPI documents.

The initial model contract is documented in docs/static-v1.md. OpenUdon consumes the Go API as the primary boundary; deterministic JSON is an export/debug projection suitable for fixtures and review artifacts.

This package is static analysis only. It does not run provider plugins, initialize backends, load state, refresh, plan, or apply.

Usage

Use the Go API as the primary integration boundary:

doc, err := tfconfig.LoadDir("./tf")
if err != nil {
    // setup error outside normal configuration diagnostics
}

Parser and decode diagnostics are recorded in the returned document. The deterministic JSON projection is available for fixtures and review artifacts:

go run ./cmd/tfconfig --config-dir ./tf

OpenTofu-derived files are MPL-2.0-covered and must preserve their upstream headers. See AGENTS.md, UPSTREAM.md, and THIRD_PARTY.md.

OpenTofu Sync

Allowlisted upstream files are listed in sync/opentofu-files.tsv. Raw upstream snapshots should normally land under _upstream/opentofu/..., which the Go tool ignores. Compile-ready parser code should then be adapted into normal tfconfig packages after review.

To sync from a local OpenTofu checkout:

OPENTOFU_DIR=../opentofu ./scripts/sync-opentofu.sh
go test ./...
go vet ./...

GitHub Actions also includes a weekly/manual workflow that runs the sync and opens a review-required pull request when files change.

The workflow uses a repository secret named TFCONFIG_SYNC_TOKEN to push the sync branch and open the pull request because the OpenUdon organization does not permit the default GITHUB_TOKEN to create pull requests. Configure it as a fine-grained token from a dedicated automation account, scoped only to this repository with Contents: Read and write and Pull requests: Read and write. No token is required when a sync run produces no changes.

The workflow is scheduled to run every Monday at 06:17 UTC:

schedule:
  - cron: "17 6 * * 1"

You can also run it manually from GitHub:

1. Open OpenUdon/tfconfig on GitHub.
2. Go to Actions.
3. Select Sync OpenTofu Static Config Sources.
4. Click Run workflow.
5. Leave opentofu_ref as main, or enter a specific OpenTofu tag or commit.

If allowlisted OpenTofu files changed, the workflow opens or updates a review-required sync pull request. If no pull request appears, the mirror is already current for the selected OpenTofu ref.