Hugo Pipes fingerprinting and CI/CD cache invalidation

Direct Answer

The fingerprint function computes a hash (default SHA-256 truncated to 12 characters) of the final processed asset content—after transpilation, minification, PostCSS, etc. It does not incorporate source-file modification time, inode, or build timestamp. The fingerprint is purely content-addressable.

Two Distinct Layers

Confusion often arises because Hugo maintains a separate on-disk build cache (default $TMPDIR/hugo_cache_<user>/ or resources/_gen/) that does use file path, size, and mtime as cache keys. This cache stores intermediate pipeline results to avoid re-running expensive transforms when the source appears unchanged. The cache is an optimization; it does not affect the fingerprint value itself.

Local Development vs. Clean CI

Environment	Build Cache State	Pipeline Execution	Fingerprint Stability
Local hugo server	Persisted, updated via fsnotify events	Re-runs only on detected content change	Stable—new fingerprint only if output content changes
Clean CI (no cache restore)	Empty	Full reprocess every build	Stable—identical source + config + Hugo version = identical fingerprint
CI with cache restore	Restored from previous run	Cache hit if path/size/mtime match; miss if mtime shifted (common with git checkout)	Stable—fingerprint unchanged even on cache miss because content is identical

Practical Implications for CI/CD

1. Fingerprint stability is guaranteed by content hashing. You can safely cache the public/ output or CDN assets across builds with no source changes.
2. Build cache effectiveness in CI depends on mtime preservation. Git checkouts typically set mtime to commit time or current time, causing cache misses and full reprocessing. This slows the build but does not change fingerprints.
3. To keep the build cache warm in CI, include a hash of relevant source files in your cache key (e.g., hashFiles('assets/**/*') in GitHub Actions) rather than relying on mtime stability.
4. Version upgrades (Hugo, PostCSS, Autoprefixer, browserslist) can alter pipeline output and thus fingerprints—even with identical source.

Verification Steps

# 1. Clean build twice; fingerprint must match
mkdir test-site && cd test-site
hugo new site .
echo "body { color: red; }" > assets/css/main.css
hugo && cp public/css/main.*.css /tmp/first.css
hugo && cp public/css/main.*.css /tmp/second.css
diff /tmp/first.css /tmp/second.css  # should be identical

# 2. Touch source without content change; fingerprint unchanged
cd test-site
touch assets/css/main.css
hugo && cp public/css/main.*.css /tmp/touched.css
diff /tmp/first.css /tmp/touched.css  # still identical

# 3. In CI, print fingerprint across two runs with no source changes
grep -o 'main\.[a-f0-9]\{12\}\.css' public/index.html

One Diagnostic Detail

Are you restoring resources/_gen/ (or $TMPDIR/hugo_cache_*) between CI runs, and observing slower-than-expected builds? If yes, the cache key likely needs to include a content hash of your asset sources to avoid mtime-induced misses.