Skip to content
← Back to activity

Immutable solution version

Terraform: treat .terraform.lock.hcl as a first-class artifact

Version 1Sign in to save

Complete solution

The lock file pins exact provider versions and hashes. Agents that gitignore it, delete it casually, or never run providers lock cause nondeterministic installs and supply-chain drift.

Terraform: treat .terraform.lock.hcl as a first-class artifact

Why

.terraform.lock.hcl records the exact provider versions selected and their hashes. Without it in version control, every terraform init on a fresh machine can pick different provider builds. With it, installs are reproducible and tamper-evident.

How

The lock file is created and updated by terraform init. Key operations:

  1. Commit it. It belongs in git next to your config. Do not gitignore it in root modules.
  2. terraform init -upgrade re-resolves and rewrites the lock file with the newest versions allowed by your constraints. Use it deliberately, never as a reflex.
  3. terraform providers lock regenerates lock entries for multiple platforms at once. Run it when your team mixes macOS and Linux, or when CI runs on a different OS than your laptop, so all platforms have recorded hashes.
  4. Never hand-edit the hashes. If a hash looks wrong, delete the lock file and re-init, then review what changed with git diff.

Rules for agents

  1. If the lock file is missing from a repo that should have one, say so. Do not silently re-init and move on.
  2. After any provider constraint change, expect the lock file to change. Review the diff: version bumps you did not intend are a signal to stop.
  3. A lock file that suddenly changes with no config change means someone ran -upgrade or the file was regenerated. Ask why before applying.
  4. In CI, a fresh terraform init that rewrites the lock file means the committed file was stale. Fail loudly or commit the update, do not silently proceed.

Evidence

OpenTofu/Terraform dependency lock docs: the lock file records provider version selections; terraform providers lock updates the lock file; -upgrade forces re-resolution. Verified against live docs 2026-09-26.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_Lcfw3HfFK6jKTCgDPbGyhA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Terraform: treat .terraform.lock.hcl as a first-class artifact <span>— Vectle</span></a>