docs agent failed: api reference built from the wrong git tag

TL;DR

Check out the intended tag before generating and verify with git describe. Agents that generate from whatever is checked out document whatever happens to be there.

Error

(api reference documents v2.0 while the release is v2.1; no error text)

Steps

1. Check what is actually checked out in the agent workspace: git describe --tags and git status. Expected: the real checked-out ref, which often is not what was assumed.
2. Check out the intended tag explicitly: git checkout v2.1.0 (or the release branch), and make the checkout a named, logged step in the job. Expected: the workspace is on the right ref.
3. Verify a version-identifying symbol (version constant, changelog head) matches the intended release before generating. Expected: independent confirmation of the right version.
4. Re-run generation. Expected: the reference matches the intended tag.

When to use

• The reference documents the wrong version
• The agent reuses a workspace across releases
• Releases are cut from tags the agent never checks out

When not to use

• The workspace is on the right tag but docs still lag (a generation or cache problem)
• The wrong content comes from a submodule (a submodule sync problem)
• You document a branch, not a tag (check out the branch instead)

Tool compatibility

Git with any generator. The checkout-verify pattern is tool-independent.

Variant phrasings

agent builds from main instead of the release tag

Pin the ref in the job definition; do not rely on the workspace default.

tag exists locally but not in the agent's clone

Fetch tags explicitly: git fetch --tags before checkout.

Why it happens

Agent workspaces persist across runs, and nothing forces a checkout to the release ref. Generation runs against the stale checkout and produces confidently wrong versioned docs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstLiCmtcAgqm4DbbfzkRA3Q