All jobs

Make a Terraform Module's CI Run on OpenTofu Too

Yes. An agent adds an OpenTofu leg to your module's pre-commit CI, runs validate on both tools in its sandbox, documents the versions and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the module is checked today before it adds a second tool. In a module like terraform-aws-modules/terraform-aws-vpc, versions.tf requires terraform >= 1.0 and hashicorp/aws >= 6.28, and .pre-commit-config.yaml runs the antonbabenko/pre-commit-terraform hooks terraform_fmt, terraform_wrapper_module_for_each, terraform_docs, terraform_tflint with an explicit --only list of rules such as terraform_required_version and terraform_standard_module_structure, and terraform_validate. .github/workflows/pre-commit.yml runs on pull requests: a collectInputs job lists every root directory, a preCommitMinVersions matrix runs terraform_validate in each of the thirteen examples/ directories and the root at the minimum Terraform version clowdhaus/terraform-min-max reads from required_version, and a preCommitMaxVersion job runs the full hook set at the maximum version with TFLINT_VERSION: v0.64.0 and TERRAFORM_DOCS_VERSION: v0.24.0. The README already has a "Known limitations (Terraform/OpenTofu, not this module)" section, so users on OpenTofu exist, but nothing in CI runs it.

The agent then checks what the hooks support. pre-commit-terraform runs whichever binary PCT_TFPATH names, so the same .pre-commit-config.yaml works unchanged with PCT_TFPATH=tofu; the composite action clowdhaus/terraform-composite-actions/pre-commit installs Terraform only, so the OpenTofu leg needs opentofu/setup-opentofu and a direct pre-commit run instead of that action. The agent adds a preCommitOpenTofu job to pre-commit.yml that needs collectInputs, installs Python and pre-commit, installs tflint at the pinned TFLINT_VERSION and OpenTofu at a pinned version from a new OPENTOFU_VERSION env, and runs pre-commit run terraform_validate --color=always --show-diff-on-failure --files <dir>/* per example directory with PCT_TFPATH=tofu. It leaves terraform_docs and terraform_fmt on the Terraform leg so generated README tables are produced by one tool only, and it does not add a second disk-cleanup step, since validate on OpenTofu needs none of the toolcache the existing jobs delete.

In the sandbox the agent installs both binaries and runs the check itself before pushing: terraform init -backend=false && terraform validate and tofu init -backend=false && tofu validate in examples/simple, examples/complete and the root, with the aws provider at the >= 6.28 floor. Where the two disagree, for example a provider-defined function or a moved block OpenTofu handles differently, it records the difference in the pull request rather than papering over it, and it does not change versions.tf, because required_version is read by terraform-min-max and already admits OpenTofu's version numbers.

Last it documents the support. It adds a short "Terraform and OpenTofu" note to the README outside the BEGIN_KNOWN_LIMITATIONS markers that terraform_docs manages, stating that CI validates every example on both tools and naming the OpenTofu version pinned in the workflow. It does not touch .releaserc.json or release.yml, since the semantic-release flow is unaffected, and it keeps the pull request title in the conventional-commit form pr-title.yml enforces, ci: validate examples with OpenTofu.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add OpenTofu validation to this Terraform module's CI and open a pull request. Read versions.tf, .pre-commit-config.yaml, .github/workflows/pre-commit.yml and the examples directory first. Add a job to pre-commit.yml that installs a pinned OpenTofu version and the same pinned tflint, and runs the existing terraform_validate pre-commit hook over each example directory and the root with PCT_TFPATH=tofu, reusing the collectInputs directory list; leave terraform_fmt and terraform_docs on the Terraform leg. Do not change versions.tf or the release workflow. In the sandbox run init -backend=false and validate on both terraform and tofu in at least examples/simple, examples/complete and the root, and quote the output. Add a short README note naming the OpenTofu version CI validates. Use a conventional-commit pull request title.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes .github/workflows/pre-commit.yml and README.md. The workflow gains an OPENTOFU_VERSION env and a preCommitOpenTofu matrix job over the same directories collectInputs already produces; the README gains a paragraph on OpenTofu support. .pre-commit-config.yaml, versions.tf and every .tf file are unchanged.

The description quotes tofu validate and terraform validate output from the sandbox for each directory the agent ran, with the exact versions of both binaries and the AWS provider that init resolved, and names any example whose behaviour differed between the two tools. The repository's own pre-commit.yml then runs on the pull request, so the new job runs once on GitHub before anyone merges.

Before merging, a reviewer checks the pinned OpenTofu version against what their users actually run, decides whether the new job should be a required check in the branch ruleset, and reads the new job's log on the pull request to see each example validate under tofu. If they want tofu fmt enforced as well, that is a one-line hook addition they can ask for in a follow-up.

Run it on every Terraform module without an OpenTofu check

A team that publishes several modules sends one POST /o/{org}/sessions per repository with this prompt and the repository in resources. GET /o/{org}/github lists the repositories the Rush GitHub App installation reaches, so a script can start a run for each module whose pre-commit.yml lacks a tofu step. Each run reads that module's own hook list, pinned tool versions and example directories, so a module with three examples and one with thirteen each get a matrix that fits.

Set a webhook URL on the API key and Rush POSTs run.completed or run.failed when the turn ends, with session_url so your script can collect the pull request links. Send a fresh UUID as request_id with each request so a retry returns the run already started.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Adding a second tool to CI means installing it, learning how the existing hooks pick a binary, and running both tools over every example to see where they differ. In its own sandbox the agent installs Terraform and OpenTofu side by side, runs validate with each over the real examples at the real provider floor, and keeps every command and its output in the run's record, so the pull request states what was tested rather than what should work.

The workflow change is small, but the confidence behind it comes from the sandbox runs, which a laptop with one of the two tools installed cannot give. The same request runs over every module a team maintains at once, each in its own sandbox, each with its own pull request.

Frequently asked questions

Will the module now require OpenTofu?

No. versions.tf keeps required_version = ">= 1.0" and nothing else changes for users. CI simply validates the examples with both binaries, so a change that only works on one of them is caught on the pull request instead of by a user.

Why not run the whole pre-commit hook set on OpenTofu?

Because terraform_docs and terraform_fmt write files, and running them under two tools invites a formatting ping-pong in generated README sections. The agent runs terraform_validate under tofu and leaves the formatting and docs hooks on the Terraform leg that already runs them.

What if an example validates on Terraform but not on OpenTofu?

The agent reports it in the pull request with both outputs and does not change the example to hide it. The reviewer decides whether to fix the example, mark it Terraform-only in the matrix, or accept the difference; the new job makes that a visible choice.

Which OpenTofu version is pinned?

The agent pins the current stable release in an OPENTOFU_VERSION env at the top of the workflow, next to the existing TFLINT_VERSION and TERRAFORM_DOCS_VERSION, so Dependabot or a person can bump it in one place. The README note quotes the same value.

More Terraform jobs

More jobs like this: Hand off a long task

Keep reading