Build Content Hash Lockfiles for Unity Addressables - A CI Artifact That Survives Branch Churn in 2026

Unity Addressables pipelines often look stable in isolation, then fail during merge week when two branches rebuild content with slightly different local states. The result is familiar: unexpected catalog drift, hard-to-reproduce patch bugs, and rollback confusion because hashes moved even when teams thought they were shipping the same payload.

The fix is not adding more manual checks at the end. The fix is creating a lockfile contract for content hashes and enforcing it in CI so branch churn cannot silently rewrite your release inputs.

Who this helps

• Unity teams shipping regular patches with Addressables remote content
• Build engineers who need deterministic Addressables output after merges
• Producers and leads who want go or hold decisions based on evidence, not assumptions

What a content hash lockfile solves

A content hash lockfile is a versioned file that records the expected hash identity for each release-relevant Addressables artifact.

It gives you:

• one source of truth for expected content identity
• fast drift detection in CI
• safer rollback because artifact identity is explicit
• cleaner branch merges because hash changes are intentional, not accidental

Without this file, teams compare logs and folders after a problem appears. With it, CI fails early when content identity changes unexpectedly.

Main keyword and intent

Primary search intent here is practical and operational:

• build content hash lockfiles for Unity Addressables

Supporting intents:

• deterministic Addressables CI artifact workflow
• prevent Addressables catalog drift after branch merges
• stable patch release and rollback with Addressables

Step 1 - Define a lockfile schema before tooling

Start simple and machine-readable. JSON works well for most teams.

Use fields like:

• build_id
• git_sha
• addressables_profile
• catalog_hash
• content_state_hash
• bundle_hashes (map of bundle name to hash)
• generated_at_utc
• owner_lane

Keep naming stable. Schema churn causes almost as many pipeline issues as hash churn.

Example lockfile shape

{
  "build_id": "ios_rc_2026_04_25_01",
  "git_sha": "a1b2c3d4",
  "addressables_profile": "Production",
  "catalog_hash": "8f6c...d11",
  "content_state_hash": "3ab1...9e2",
  "bundle_hashes": {
    "characters_all.bundle": "91aa...f02",
    "ui_core.bundle": "0c54...2bd"
  },
  "generated_at_utc": "2026-04-25T09:10:44Z",
  "owner_lane": "release-engineering"
}

This is enough to catch most accidental identity drift.

Step 2 - Generate lockfile as a first-class CI artifact

Do not generate lockfiles only on developer machines. Generate them in the same CI context that performs release candidate Addressables builds.

Recommended flow:

1. run clean Addressables build in CI
2. collect catalog and bundle hash outputs
3. generate lockfile from these outputs
4. upload lockfile as immutable artifact with build metadata

If a release branch has no lockfile artifact, treat that branch as not release-ready.

Step 3 - Add branch merge drift checks

After merging into release branch, CI should compare:

• latest lockfile from source branch
• newly generated lockfile on merged branch

Then classify differences:

• expected drift (content changed intentionally)
• suspicious drift (hash changed without planned content delta)

Fail the pipeline on suspicious drift until owner approves a documented reason.

This one gate prevents many late-night catalog incident loops.

Step 4 - Separate intended content edits from incidental rebuild noise

A common failure mode is re-running full builds that rewrite identity for unrelated bundles.

Set explicit criteria for a valid hash change:

• content file or dependency changed in scoped group
• profile or build config changed intentionally
• platform-targeted pack change approved in release note

If none apply, hash movement is likely noise and should block promotion.

Step 5 - Tie lockfile to rollback packet

For every candidate release packet, include:

• lockfile artifact URL
• lockfile checksum
• linked catalog and content state outputs
• prior release lockfile reference

If rollback is needed, you can reconstruct exact prior identity quickly instead of guessing which build produced the currently live catalog.

Practical CI gate model

Use three binary gates:

This gives release leads a clear go or hold frame during busy patch windows.

Common mistakes

Mistake 1 - Storing only catalog hash

Fix: include content state hash and per-bundle hash map. Catalog-only visibility is too shallow.

Mistake 2 - Letting lockfile format change ad hoc

Fix: version your schema and treat changes as engineering tasks with migration notes.

Mistake 3 - Comparing lockfiles manually during release meetings

Fix: classify drift in CI and emit a compact summary artifact before review.

Mistake 4 - Allowing hotfix branches to skip lockfile gates

Fix: hotfix speed does not remove identity risk. Use smaller scope, but keep the lockfile contract.

Pro tips for tiny teams

• Keep one lockfile validator script in repo so local and CI checks stay aligned
• Track first-seen drift type to identify recurring branch hygiene problems
• Add a lockfile diff summary to release notes to improve non-engineering visibility
• Keep lockfile artifacts immutable once attached to a release candidate

Related learning

• Addressables Remote Catalog Drift in Unity 6 - A Production-Safe Validation Loop for Patch Weeks 2026
• Unity Build Profile Signings and Preflight Checklist
• How to Run a Launch-Day Command Center Without Burnout - A Shift Handoff Template for Teams Under 8 People
• Addressables Profile Variable Preflight Checklist
• Unity Cloud Diagnostics Symbol Upload Failed - dSYM and ProGuard Mapping Pipeline Fix

External references

• Unity Manual - Addressables
• Unity Addressables package documentation

FAQ

Do we need lockfiles if we already track build numbers

Yes. Build numbers identify releases, not content identity. Lockfiles identify what content hashes were actually shipped.

Should lockfiles be committed to git or only stored in CI

Both can work. Many teams keep lockfiles as CI artifacts and commit only promoted lockfiles for release tags. The key is immutable traceability.

How often should we regenerate lockfiles

Every release candidate and every hotfix candidate. Lockfiles are cheap to generate and expensive to skip.

What if lockfile drift is expected during a planned content update

Mark it as approved drift with explicit reason and owner. Expected drift is fine when it is documented and reviewed.

Bottom line

A Unity Addressables content hash lockfile turns fragile branch-merge assumptions into a deterministic release contract. If your CI enforces lockfile generation, drift classification, and rollback evidence, branch churn stops being a silent source of patch risk.

Found this useful? Bookmark it for your next patch week and share it with the teammate who owns Addressables promotion gates.