[AVM Module Issue]: hardcoded version pins in submodule `_header.md` usage examples go stale on every release

[andyleejordan]

Check for previous/existing GitHub issues

• I have checked for previous/existing GitHub issues

Issue Type?

Bug

(Optional) Module Version

0.10.2

(Optional) Correlation Id

N/A

Description

Follow-up from #204 / PR #308.

PR #308 added consumer-facing usage examples to the submodule docs, each pinning the module version:

module "keyvault_secret" {
  source  = "Azure/avm-res-keyvault-vault/azurerm//modules/secret"
  version = "0.10.2"
  # ...
}

The version is hardcoded in modules/key/_header.md and modules/secret/_header.md. Nothing in the release process updates those files, so the moment 0.10.3 ships the published documentation advertises a stale pin. Every subsequent release widens the gap, and the drift is silent — the docs still generate cleanly and CI stays green, because terraform-docs copies _header.md verbatim into README.md without validating its contents.

This is not specific to the two files added in #308. It applies to any version pin baked into an _header.md anywhere in this repo, including the root _header.md if a usage example is ever added there. Worth solving generically rather than patching the two current instances.

Possible approaches (not prescriptive — whichever fits the AVM tooling best):

1. Have the release automation rewrite version = "x.y.z" occurrences in _header.md files as part of the release commit, then regenerate docs.
2. Replace the literal pin with a placeholder plus a pointer to the registry's version list, accepting that the example is then not copy-pasteable as-is.
3. Add a CI check that fails when a version pin in an _header.md does not match the latest published release, converting silent drift into a visible failure.

Option 1 keeps the examples copy-pasteable and correct, which was the point of #204 in the first place, but it needs a hook in the release workflow. Option 3 is the cheapest to implement and at least makes the problem loud.

Files currently affected:

• modules/key/_header.md
• modules/secret/_header.md

Drafted by Claude Opus 5.

[github-actions]

🤖 GitHub Agentic Workflow Automated Triage 🤖

⚠️ This triage was generated automatically by an AI agent and may be incomplete or inaccurate.

• Duplicate check: No duplicates found. Issue auto-docs doesn't make the expected example #204 is the parent issue (submodule docs showing wrong call pattern), and PR docs: add registry usage examples to key/secret submodule docs #308 is the open PR that introduces the hardcoded version pins this issue is tracking. Issue [AVM Module Issue]: hardcoded version pins in submodule _header.md usage examples go stale on every release #312 is a forward-looking concern that pre-emptively tracks the version drift that will follow once PR docs: add registry usage examples to key/secret submodule docs #308 merges — it is a new, distinct issue.

• Labels applied:

  • Type: CI :rocket: — the proposed resolutions (release automation hook or CI lint check) are CI/release workflow concerns, complementing the existing Type: Documentation label.

• Existing fix: None. PR docs: add registry usage examples to key/secret submodule docs #308 is still open and not yet merged, meaning the _header.md files on main do not yet contain any version pins. The problem described will materialise the moment PR docs: add registry usage examples to key/secret submodule docs #308 is merged; no release has shipped a fix.

• Suggested fix: The issue clearly describes the problem and three viable approaches. From a code-investigation standpoint:

  • The relevant files are modules/key/_header.md and modules/secret/_header.md (will contain version = "0.10.2" once PR docs: add registry usage examples to key/secret submodule docs #308 merges).
  • Option 3 (cheapest): Add a CI step that greps _header.md files for version = "x.y.z" and fails if the pinned version does not match the latest published/git tag. A simple grep -r 'version\s*=\s*"[0-9]' modules/ _header.md combined with a tag comparison would catch drift.
  • Option 1 (best UX): Extend the release workflow (e.g. .github/workflows/release.yml) with a step that runs sed -i "s/version = \"[^\"]*\"/version = \"$NEW_VERSION\"/" modules/*/_header.md and re-runs terraform-docs before tagging, keeping examples copy-pasteable and accurate.
  • Option 1 requires touching the release workflow but yields the best result; Option 3 is safer to implement first as a safeguard regardless of which long-term approach is chosen.

🔎 What this triage looked at

• Searched issues for: hardcoded version _header.md stale, version pin submodule documentation
• Read issue auto-docs doesn't make the expected example #204 (parent issue about submodule autodocs) and PR docs: add registry usage examples to key/secret submodule docs #308 (the open PR that adds the version-pinned examples) to confirm [AVM Module Issue]: hardcoded version pins in submodule _header.md usage examples go stale on every release #312 is a new, forward-looking tracking issue rather than a duplicate
• Read modules/secret/_header.md and modules/key/_header.md on main — confirmed no version pins exist yet (PR docs: add registry usage examples to key/secret submodule docs #308 not merged)
• Reviewed the 5 most recent releases (v0.10.2 down to v0.9.0) — no release notes mention updating _header.md version pins or release automation for docs
• Checked PR docs: add registry usage examples to key/secret submodule docs #308 description which explicitly notes: "The hardcoded 0.10.2 will drift on future releases since nothing auto-bumps _header.md. Tracked separately in [AVM Module Issue]: hardcoded version pins in submodule _header.md usage examples go stale on every release #312."

Generated by Azure Verified Modules Terraform Module Issue Triage for issue #312 · 25.2 AIC · ⌖ 4.89 AIC · ⊞ 10K · ◷