Git Tags
debt(d9/e3/b5/t7)
Closest to 'silent in production until users hit it' (d9). The detection_hints note automated=no and the code_pattern describes absence of tags as the problem — there is no compiler, linter, or SAST that flags missing tags. The gap only becomes visible when a rollback is needed and there is no anchor commit, or when deployment automation fails silently. Tools listed (git, github, semantic-release) can surface tags but none alert on their absence automatically.
Closest to 'simple parameterised fix' (e3). The quick_fix is a two-command pattern: git tag -a v1.2.3 -m 'Release notes' && git push --tags. While tagging a single release is one line, the common_mistakes list includes tagging wrong commits and missing historical tags for past releases, meaning a team catching up must apply the pattern retroactively across multiple releases — slightly beyond a pure one-liner but well within a small localised fix.
Closest to 'persistent productivity tax' (b5). tags apply_to any context, and missing or inconsistent tagging affects release automation, changelog generation, rollback procedures, and deployment artifact tracing across the entire team's workflow. It is not load-bearing in a single component (b3) but it imposes an ongoing tax on every release cycle and every workflow that depends on versioned history, touching many work streams without fully defining the system's shape (b7).
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception is explicit: developers assume git push origin pushes tags because git push pushes commits and branches. This directly contradicts the intuitive model of how push works for other refs, and the common_mistakes confirm this is a consistent source of confusion (forgetting to push tags, using lightweight instead of annotated tags). The 'obvious' action leaves tags unpushed silently, making it a serious behavioral surprise.
Also Known As
TL;DR
Explanation
Lightweight tags are simply named pointers to commits (like branches that never move). Annotated tags are stored as full git objects with tagger identity, timestamp, and message — and can be GPG-signed. Annotated tags are preferred for releases because they carry metadata and appear in git describe output. Tags are not pushed automatically — you must git push origin --tags or push individual tags. Semantic versioning is typically implemented with annotated tags.
Diagram
flowchart LR
COMMIT[Git commit] -->|annotated tag| ATAG[git tag -a v1.0.0 -m Release]
COMMIT -->|lightweight tag| LTAG[git tag v1.0.0]
ATAG -->|push tags| REMOTE[git push origin --tags]
subgraph Tag_Types
ANNOT[Annotated<br/>has message tagger date<br/>recommended for releases]
LIGHT[Lightweight<br/>just a pointer<br/>for temporary marks]
end
subgraph Release_Flow
CODE[Merge to main] --> TAG2[Create annotated tag]
TAG2 --> CI2[CI detects tag<br/>builds release artifact]
CI2 --> DEPLOY2[Deploy to production]
end
style ATAG fill:#238636,color:#fff
style CI2 fill:#1f6feb,color:#fff
style DEPLOY2 fill:#238636,color:#fff
Common Misconception
Why It Matters
Common Mistakes
- Using lightweight tags for releases — annotated tags are preferred as they store who tagged and when.
- Forgetting to push tags — git push does not push tags by default.
- Not using semver for tag names — v1.2.3 format enables tooling like git describe and release automation.
- Tagging the wrong commit — always verify HEAD before tagging, especially after a merge.
Code Examples
# Lightweight tag — no metadata:
git tag v1.2.3
git push origin main # Tag NOT pushed!
# Deploy pipeline cannot find the tag# Annotated tag with message — correct for releases:
git tag -a v1.2.3 -m 'Release 1.2.3: fixes #42, adds user export'
git push origin v1.2.3 # Push specific tag
# Or push all tags: git push origin --tags