Update an OpenTofu CI toolchain without changing provider selections
An infrastructure repository can have a clean plan while its CI runner is using an old OpenTofu binary. That matters when a maintenance release fixes a security issue in the runtime, but it is also a point where an apparently simple version bump can accidentally refresh providers, modules, or backend behavior.
This guide updates a Linux CI toolchain to OpenTofu 1.12.5, verifies the release archive before using it, and adds a read-only initialization and validation path. The resulting job proves three separate things: the runner is executing the intended OpenTofu release, the committed provider lock file is sufficient to reproduce dependency selection, and the configuration is syntactically valid before a plan reaches a real backend or cloud API. The commands are documentation-verified. The archive checksum and OpenTofu version command were also tested in an isolated Linux environment; adapt runner labels, artifact storage, and authentication to the local CI platform.
OpenTofu published 1.12.5 on 21 July 2026. Its release notes say earlier 1.12 releases could be affected by an Encrypted Client Hello issue in the Go standard library that could expose pre-shared-key identities to a passive observer. Treat that as a reason to schedule a controlled toolchain update, not as evidence that a particular state backend or provider was exposed. Confirm the release notes and the security process that applies to the network paths used by the organization before closing the change.
Separate the OpenTofu binary from provider selection
There are two version decisions in a normal OpenTofu run. The executable is the OpenTofu release installed on the runner. Providers are plugins selected from the configuration’s required_providers constraints and recorded in .terraform.lock.hcl. Remote modules are different again: OpenTofu does not record their selected versions in that lock file, so a reusable module should have an exact version or another deliberate immutable reference.
Keeping these decisions separate makes the update reviewable. A change from OpenTofu 1.12.4 to 1.12.5 should normally change the runner image, tool bootstrap, or tool-version file. It should not rewrite .terraform.lock.hcl merely because the runner was refreshed. If the lock file changes, review it as a provider dependency change with its own reason and testing.
Start by locating the executable installation and the dependency lock file in the repository:
tofu version
find . -name .terraform.lock.hcl -print
git status --short
git diff -- .terraform.lock.hcl
Run these commands from the root module or repeat them for each independently initialized module. tofu version identifies the program used by the current shell; do not infer it from an image tag or a CI step name. A clean Git status before initialization is important because tofu init can create or update the lock file when it chooses dependencies. The final command gives reviewers a focused way to see whether an earlier run already changed provider selections.
For a repository that commits its lock file, a missing lock file is a condition to resolve before a runtime-only update. Generate and review it in a separate change using the project’s supported platforms. Do not solve the missing-file error in the security-update pull request by silently allowing CI to select the newest provider releases.
Download a specific, checked release
Use the archive and SHA-256 manifest attached to the official OpenTofu release. Store the binary in a CI tools directory or a pinned runner image rather than replacing a system package during a job. This Linux x86-64 example keeps the downloaded files in a temporary directory:
set -eu
version=1.12.5
archive="tofu_${version}_linux_amd64.tar.gz"
base="https://github.com/opentofu/opentofu/releases/download/v${version}"
curl -fsSLO "$base/$archive"
curl -fsSLO "$base/tofu_${version}_SHA256SUMS"
grep " $archive$" "tofu_${version}_SHA256SUMS" | sha256sum -c -
tar -xzf "$archive" tofu
install -m 0755 tofu "$RUNNER_TEMP/tofu-${version}"
"$RUNNER_TEMP/tofu-${version}" version
The checksum command must print OK before extraction. The grep restricts the manifest entry to the chosen archive, avoiding a check against an unrelated platform artifact. The example assumes RUNNER_TEMP is a CI-provided writable temporary location; replace it with an equivalent location on another runner. If the project uses an image build, perform the same checksum verification when producing the image and pin the image digest in the workflow.
Do not use a floating latest URL for an infrastructure toolchain. A later job could then run a different binary with the same configuration and commit. Keep the version in one reviewed location, such as a workflow environment variable, a tool-version file, or the runner-image definition.
Initialize without refreshing the lock file
After putting the verified binary on PATH, initialize the root module with backend initialization disabled and the lock file in read-only mode:
export PATH="$RUNNER_TEMP:$PATH"
tofu init -input=false -backend=false -lockfile=readonly
tofu validate -json > validate.json
-backend=false prevents this initialization step from configuring the module’s backend. That makes it suitable for an early CI check that should not need state credentials. It does not make provider installation offline: a fresh runner may still need access to the provider packages already selected by .terraform.lock.hcl. Use an approved provider mirror or cache if the CI network cannot contact the configured registry.
-lockfile=readonly is the guardrail. OpenTofu must use the provider versions already selected in .terraform.lock.hcl; it must not write a new selection. A failure because a provider is unavailable for the runner platform or the lock file needs an update is a review signal, not a reason to remove the flag. Address it in a dedicated dependency change, test all supported platforms, and commit the resulting lock-file update deliberately.
tofu validate checks configuration syntax and internal consistency but does not read state or call provider APIs. The JSON file is useful for CI annotations or a retained artifact, but it can include resource names and file paths. Keep it in the project’s normal access-controlled build artifacts rather than posting it to a public log if those names are sensitive.
Add a plan stage with an explicit boundary
Validation does not prove that a plan can authenticate to a real backend, resolve data sources, or read the current state. Put that work in a separate stage with the minimum credentials and an explicit workspace selection. A non-applying plan is still an operational read of the target environment, so run it only in a repository and account the pipeline is authorized to inspect.
tofu plan \
-input=false \
-no-color \
-out=planned.tfplan
tofu show -json planned.tfplan > planned.json
tofu plan proposes changes but does not apply them. Saving the plan makes it possible to review the exact proposal that a later approved apply would use. It does not make the plan permanent: real infrastructure can change between planning and approval, so a deployment process should re-check its final plan according to its change-control policy.
Do not upload planned.tfplan or planned.json to an unrestricted artifact location. A plan can contain values derived from state, provider responses, or input variables. Mark the artifact as sensitive where the CI platform supports it, limit retention, and avoid printing the full JSON document in job logs. If the job uses cloud identity federation, scope the planning role to the intended account, workspace, and read actions rather than reusing an apply-capable credential.
Verify the update before making it routine
Use a disposable branch or an owned non-production workspace for the first run. Confirm the version output says OpenTofu v1.12.5, the checksum check succeeded, and tofu init -lockfile=readonly did not modify .terraform.lock.hcl. Confirm that validate.json reports a valid configuration. For the plan stage, compare the human-readable proposal to the expected change and verify that no apply command was invoked.
Then inspect the CI job’s effective environment: the runner image or bootstrap step should reference the pinned version, and a normal pull request should not receive production backend credentials merely to run syntax validation. If a provider update is required separately, make it a distinct pull request with a reviewed lock-file diff and a test in the affected environments.
The finished result is a small but useful boundary around an OpenTofu runtime update. Version 1.12.5 is verified before execution, provider selection remains under source control, and the CI pipeline distinguishes safe configuration validation from an authorized infrastructure plan. That makes a maintenance release easier to adopt without turning it into an unreviewed dependency refresh.