Lesson 261: Unity CI Library Cache Addressables Receipt on BUILD_RECEIPT (2026)

Direct answer: Before October 2026 Addressables group moves merge, promote unity_ci_library_cache_receipt_v1.json proving AddressablesContentState.bin sha256 is in the actions/cache key, a clean-library-on-group-move job is linked, Temp/ clears on player build, and library_cache_bust_ok fail-closes fest promotion—distinct from Lesson 257 (addressables_audit_jq_receipt_v1 inventory schema) and 7-day key audit (addressables_key_audit_receipt_v1 calendar). Pair the Unity Library cache + ContentState preflight (Guide #24).

Why this matters now (October strip week CI)

October 2026 teams move Addressables groups Tuesday, merge Wednesday, and trust a green GitHub Actions badge—then fest players hit InvalidKeyException because actions/cache restored a stale Library/ that never rebuilt catalog content. CI compiled; player smoke failed. Lesson 257 guards inventory groups[]; 261 guards cache key material and Library bust policy on BUILD_RECEIPT.

The Library cache preflight is the ninety-second gate—261 is the BUILD_RECEIPT milestone.

Beginner path (hash → cache key → receipt)

Time: ~50 minutes first October strip week; ~12 minutes when workflow template exists.

Developer path (gates C1–C6)

C1 — cousin receipt crosswalk

Do not merge schemas—reference paths in cousin_receipts only.

C1 — Locate and hash AddressablesContentState

Default path after Addressables build:

Library/com.unity.addressables/AddressablesContentState.bin

sha256sum Library/com.unity.addressables/AddressablesContentState.bin

PowerShell:

Get-FileHash "Library\com.unity.addressables\AddressablesContentState.bin" -Algorithm SHA256

Log hash, build_label, and K1 inventory sha256 in receipt.

C2 — Cache key sketch (GitHub Actions)

- name: Hash Addressables content state
  id: addr_state
  shell: bash
  run: |
    STATE="Library/com.unity.addressables/AddressablesContentState.bin"
    if [ -f "$STATE" ]; then
      echo "hash=$(sha256sum "$STATE" | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
    else
      echo "hash=missing" >> "$GITHUB_OUTPUT"
    fi

- uses: actions/cache@v4
  with:
    path: Library
    key: unity-library-${{ runner.os }}-${{ hashFiles('ProjectSettings/ProjectVersion.txt', 'Packages/manifest.json') }}-${{ steps.addr_state.outputs.hash }}
    restore-keys: |
      unity-library-${{ runner.os }}-${{ hashFiles('ProjectSettings/ProjectVersion.txt', 'Packages/manifest.json') }}-

Fail-closed: If steps.addr_state.outputs.hash == missing on Addressables build job, fail the workflow—do not restore unbounded Library/.

C3 — Clean job after group move

clean-library-on-group-move:
  if: github.event_name == 'workflow_dispatch'
  runs-on: ubuntu-latest
  steps:
    - run: rm -rf Library Temp

Trigger when Lesson 257 inventory diff shows group changes—or automate on address_inventory_v1.json diff.

C4 — Temp/ hygiene

- name: Clear Temp before player build
  run: rm -rf Temp

C5 — Fail-closed promotion jq (CI tail)

jq -e '.library_cache_bust_ok == true' release-evidence/unity/ci-cache/unity_ci_library_cache_receipt_v1.json

Block merge to fest branch when receipt missing or false—pair Wednesday smoke.

unity_ci_library_cache_receipt_v1.json

{
  "schema": "unity_ci_library_cache_receipt_v1",
  "build_label": "october-fest-2026-rc3",
  "addressables_content_state_path": "Library/com.unity.addressables/AddressablesContentState.bin",
  "addressables_content_state_sha256": "b7e2c4a1…",
  "inventory_path": "release-evidence/unity/addressables-jq/address_inventory_v1.json",
  "inventory_sha256": "aa11ff00…",
  "cache_key_template": "unity-library-{os}-{project}-{packages}-{content_state_hash}",
  "workflow_path": ".github/workflows/unity-addressables-ci.yml",
  "clean_library_job": "clean-library-on-group-move",
  "cousin_receipts": {
    "jq_audit": "release-evidence/unity/addressables-jq/ADDRESSABLES_AUDIT_JQ_RECEIPT.json",
    "key_audit_week": "release-evidence/unity/addressables-audit-week/addressables_key_audit_receipt_v1.json"
  },
  "gates": {
    "C1_content_state": "pass",
    "C2_cache_key": "pass",
    "C3_clean_job": "pass",
    "C4_temp_clear": "pass",
    "C5_fail_closed": "pass",
    "C6_build_receipt": "pass"
  },
  "library_cache_bust_ok": true,
  "content_update_promotion_allowed": true
}

Pin under release-evidence/unity/ci-cache/UNITY_CI_LIBRARY_CACHE_RECEIPT.json.

BUILD_RECEIPT row (C6)

Thursday row review — Library cache bust line: ContentState in key Y/N.

Key takeaways

1. AddressablesContentState hash belongs in the cache key—branch name alone hides group moves (C2).
2. Manual clean job after group moves beats player-only InvalidKeyException (C3).
3. Fail-closed library_cache_bust_ok before fest branch promotion (C5).
4. Lesson 257 = inventory jq; 261 = CI cache material.
5. 7-day challenge owns K1–K7 calendar; 261 owns BUILD_RECEIPT cache column.
6. Library cache preflight — ninety-second gate before this lesson.
7. Cousin: Lesson 262 — GameMaker Steam partner BUILD_RECEIPT column (gm_steam_partner_receipt_v1.json).
8. October capstone 265 wires 254–264 including this row.
9. Help #26 (planned) — fix lane for stale Library after cancel.
10. 15-free GitHub Actions CI recipes — workflow graph vs cache bust.
11. 3-day false-green challenge — F1–F6 ladder after group moves.

Common mistakes

• Cache key = git branch only (C2 fail).
• Green CI without player smoke after group move.
• Restoring Library/ after deleting groups without busting key.
• Deleting jq guard instead of fixing inventory (Lesson 257 J5).
• concurrency: cancel-in-progress mid-Addressables build without clean job (Help #30 cousin).

Troubleshooting

Mini exercise (45 minutes)

1. Move one Addressables group—confirm ContentState hash changes.
2. Reproduce false-green CI with old cache key—confirm player fail.
3. Add ContentState to cache key + clean job—confirm pass.
4. Wire C5 jq gate in workflow.
5. File receipt; BUILD_RECEIPT GREEN.

Continuity — October–Q4 2026 fest ops truth (254–265)

Previous: Lesson 260 — Unity UGS OTLP diligence
Next: Lesson 262 — GameMaker Steam partner receipt

FAQ

Same as Lesson 257?
257 = inventory groups[] + jq CI guard; 261 = actions/cache key + Library bust BUILD_RECEIPT column.

Same as 7-day challenge?
Challenge owns K1–K7 calendar; 261 owns unity_ci_library_cache_receipt_v1 on BUILD_RECEIPT.

Need to delete actions/cache entirely?
No—include ContentState hash; run clean job on group moves.

Blog #13 evening tutorial?
Evening cache-bust tutorial—261 is course milestone with fail-closed promotion.

3-day false-green challenge?
F1–F6 ladder verifies cache bust after group moves—cousin to 261, not duplicate BUILD_RECEIPT column.

UGS diligence related?
Parallel October column—run Lesson 260 for telemetry; 261 for Addressables CI cache.

October CI lies when Library/ cache outlives Addressables group moves—hash AddressablesContentState, link a clean job, fail-closed library_cache_bust_ok, then promote.