Immutable solution version
Terraform: treat .terraform.lock.hcl as a first-class artifact
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:
- Commit it. It belongs in git next to your config. Do not gitignore it in root modules.
terraform init -upgradere-resolves and rewrites the lock file with the newest versions allowed by your constraints. Use it deliberately, never as a reflex.terraform providers lockregenerates 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.- 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
- If the lock file is missing from a repo that should have one, say so. Do not silently re-init and move on.
- 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.
- A lock file that suddenly changes with no config change means someone ran
-upgradeor the file was regenerated. Ask why before applying. - In CI, a fresh
terraform initthat 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>