DEV Community

hao li
hao li

Posted on

Your tag says v1.2.3. But is that really what you shipped?

#opensource #showdev #python

Your tag says v1.2.3. But is that really what you shipped?

Most release tooling answers one question: does the tag exist?

I built something that answers a harder one: does the tag point at the code the release was actually built from?

The failure mode nobody checks

Picture this: tag v1.2.3 exists, CI is green, the release notes look great. But somewhere between the build and the tag, someone force-pushed the tag, or the release was cut from a dirty working tree. The name matches. The content doesn't.

That's tag drift — and it's a supply-chain integrity problem. If the tag doesn't reflect the artifact, then every downstream consumer verifying "I trust v1.2.3" is trusting a label, not code.

Introducing tagpoint

tagpoint is a stdlib-only Python CLI that checks whether a PyPI release actually matches its GitHub tag — name and content:

pip install tagpoint
tagpoint check requests --repo psf/requests
Enter fullscreen mode Exit fullscreen mode 
tagpoint report: requests==2.32.3  repo=psf/requests
tag: v2.32.3   commit: abc123def456

[PASS] tag-exists: tag v2.32.3 -> abc123def456
[PASS] sdist-version: PKG-INFO version 2.32.3 matches PyPI
[PASS] file-list: 128 files match the tag tree
[PASS] tag-before-build: tag commit 2024-05-29T... <= upload 2024-05-29T...

verdict: CONSISTENT
Enter fullscreen mode Exit fullscreen mode

Four checks, no dependencies:

  1. tag-exists — a tag named v{version} or {version} resolves (annotated tags are peeled to the commit).
  2. sdist-version — the sdist's PKG-INFO version equals the PyPI version.
  3. file-list — the sdist file list matches the tag's git tree, catching files added or removed after the build.
  4. tag-before-build — the tag commit isn't newer than the release upload. A tag moved after the build is drift.

Exit codes are CI-friendly: 0 = consistent, 1 = inconsistent, 2 = check error.

How it's different

This grew out of a roadmap item in my tagtruth project: tagtruth verifies that release tags exist as part of release hygiene. tagpoint is the next step — it verifies the tag points at the right content. Existence is hygiene; correspondence is integrity.

Think of it as a "name matches reality" check for your supply chain. It won't replace Sigstore or SLSA attestations, but it's a five-second check you can drop into any release pipeline today.

Try it

If it flags drift in a package you depend on, I'd genuinely like to hear about it — that's the signal this tool is for.

Top comments (0)