ENG-3757: Fix Fides.version showing dev decorations on tagged Docker builds

[adamsachs]

Ticket ENG-3757

Description Of Changes

Fides.version (the version exposed by the FidesJS SDK) and version.json (its source inside the container) were being decorated with dev-style suffixes — e.g. 2.84.6.dev0+g<sha>.d<date> — even on tagged release builds where the running container actually corresponds to a clean tag (e.g. 2.84.5).

Root cause: The Docker build copies the host's .git directory in but applies .dockerignore to the worktree, so files tracked by the host's .git/index are missing from the container's worktree. setuptools-scm (which hatch-vcs wraps) sees this as a dirty tree and applies its dirty-tag heuristic — it bumps the version to the next patch, appends .dev0, and tacks on a local-version segment with the SHA and date. The previous versioneer-based version export was less aggressive about decorating dirty trees, so this regression landed quietly when the version step was switched to hatch version in #7328 (the "Switch to uv" PR).

The same problem already existed at PyPI publish time and was solved in .github/workflows/publish_package.yaml by setting SETUPTOOLS_SCM_PRETEND_VERSION from the tag. This PR applies the equivalent override inside the Dockerfile: when HEAD is on an exact tag, the env var is set to that tag and hatch version returns the tag verbatim. Off-tag builds are unaffected and continue to produce <next>.devN+g<sha>.d<date> so dev images remain uniquely identifiable.

This also incidentally fixes the Python webserver's reported version on Docker images built outside of the PyPI publish pipeline (the clean_version() regex in src/fides/common/utils.py was written for versioneer's output format and does not strip setuptools-scm's dev0+g<sha>.d<date> decoration). After this change, both Fides.version (frontend) and __version__ (backend) report the clean tag on tagged Docker builds.

Code Changes

• Dockerfile — when HEAD is on an exact tag, set SETUPTOOLS_SCM_PRETEND_VERSION from git describe --tags --exact-match before invoking hatch version, mirroring the override already used in .github/workflows/publish_package.yaml. Comment added explaining the .dockerignore interaction so this isn't rediscovered later.

Steps to Confirm

These steps verify both the tagged-release path (clean version) and the off-tag dev path (decorated version) inside the actual Docker build, since the dirty-tree behavior cannot be reproduced on the host.

1. Pull the branch and create a local test tag on the tip commit. A test tag is needed because the override only fires when HEAD is on an exact tag. Use any PEP 440-valid version string that doesn't collide with a real release:

   git fetch origin ENG-3757-fix-fides-js-version-dirty-tree
   git checkout ENG-3757-fix-fides-js-version-dirty-tree
   git tag 99.99.99
   

2. Build the backend stage of the Docker image. Targeting the backend stage skips the frontend build and is sufficient for this verification — version.json is generated in this stage.

   docker build --target backend -t fides-vtest .
   

3. Read version.json from the built image. Expected: the clean tag, with no decoration.

   docker run --rm --entrypoint cat fides-vtest /fides/version.json
   

   Expected output: {"version": "99.99.99"}
   Pre-fix this would have returned: {"version": "99.99.100.dev0+g<sha>.d<date>"}

4. Verify the off-tag (dev) path still produces a sensible decorated version. Delete the tag and rebuild without cache so the version step re-runs:

   git tag -d 99.99.99
   docker build --no-cache --target backend -t fides-vtest-notag .
   docker run --rm --entrypoint cat fides-vtest-notag /fides/version.json
   

   Expected output: a string of the form <next>.devN+g<sha>.d<date> (e.g. 2.84.1b1.dev81+gcc93122c4.d20260508). This confirms dev images remain uniquely identifiable and the override is correctly scoped to tagged builds only.

5. (Optional) End-to-end sanity check via FidesJS. Build the full image (no --target), boot the privacy center / consent flow, and confirm Fides.version in the browser console matches the tag rather than a decorated dev string. This is the surface where the bug was originally observed but is not strictly necessary if the version.json checks above pass — version.json is the single input that flows into the JS bundle.

Pre-Merge Checklist

• Issue requirements met
• All CI pipelines succeeded
• CHANGELOG.md updated
  • Add a db-migration This indicates that a change includes a database migration label to the entry if your change includes a DB migration
  • Add a high-risk This issue suggests changes that have a high-probability of breaking existing code label to the entry if your change includes a high-risk change (i.e. potential for performance impact or unexpected regression) that should be flagged
  • Updates unreleased work already in Changelog, no new entry necessary
• UX feedback:
  • All UX related changes have been reviewed by a designer
  • No UX review needed
• Followup issues:
  • Followup issues created
  • No followup issues
• Database migrations:
  • Ensure that your downrev is up to date with the latest revision on main
  • Ensure that your downgrade() migration is correct and works
    • If a downgrade migration is not possible for this change, please call this out in the PR description!
  • No migrations
• Documentation:
  • Documentation complete, PR opened in fidesdocs
  • Documentation issue created in fidesdocs
  • If there are any new client scopes created as part of the pull request, remember to update public-facing documentation that references our scope registry
  • No documentation updates required

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
fides-plus-nightly	Ignored		May 8, 2026 6:02pm
fides-privacy-center	Ignored		May 8, 2026 6:02pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.23%. Comparing base (292d8b2) to head (d0503d7).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8147   +/-   ##
=======================================
  Coverage   85.23%   85.23%           
=======================================
  Files         638      638           
  Lines       42011    42011           
  Branches     4937     4937           
=======================================
  Hits        35807    35807           
  Misses       5096     5096           
  Partials     1108     1108           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[adamsachs]

/code-review

[claude]

Code Review: Fix Fides version on tagged Docker builds

This is a clean, minimal fix for a real build-time problem. The root cause explanation in the new comment block is accurate and helpful — the .dockerignore exclusions cause setuptools-scm to see a dirty tree, which appends dev decorations to the version string on tagged release builds.

What the fix does

1. Detects whether the current git HEAD lands exactly on a tag using git describe --tags --exact-match.
2. If so, sets SETUPTOOLS_SCM_PRETEND_VERSION to that tag value, which bypasses setuptools-scm's git tree inspection entirely.
3. Falls through to normal hatch version behavior for non-tagged builds (dev/CI builds continue to get the expected devN+g<sha> suffix).

Assessment

Correctness: The approach is sound and consistent with the wheel build workflow referenced in the comment. The || true ensures the RUN step doesn't fail on non-tagged commits. The if [ -n "$EXACT_TAG" ] guard correctly leaves the env var unset when not on a tag.

Shell semantics: export inside the if block within a single RUN command is correct — all commands in the layer share the same shell process, so the variable is visible to the subsequent hatch version call.

Tag format: See inline comment — worth a quick sanity check that the v-prefix behavior (if applicable) matches expectations, though setuptools-scm handles this correctly in practice.

Changelog: Entry is present and accurately describes the fix.

No blocking issues. LGTM with the minor note above.

---

🔬 Codegraph: connected (49514 nodes)

---

💡 Write /code-review in a comment to re-run this review.

[gilluminate]

tested locally, works exactly as expected. 👍