Your First BUILD_RECEIPT.json and Upload Log in One Evening - 2026 Beginner Pipeline

You exported a zip, uploaded it somewhere, and three days later you cannot remember whether that build included Tuesday’s hotfix. Partners ask for “the receipt” and you send a Discord screenshot. That is not governance—it is hope.

May 2026 is when micro-studios discover that SHA256 cold validation and partner ZIP naming only work if you can answer one question first: which commit produced the bytes you uploaded? This Tutorials & Beginner-First guide teaches BUILD_RECEIPT.json plus a simple upload_log.csv in one evening—no Jira plugins, no paid release orchestration.

Who this is for and what you get

Time: one evening (~90 minutes) for templates; five minutes per upload afterward.
Prerequisites: Git (or another VCS), a release-evidence/ folder, and one build you can freeze tonight.

Why this matters now (May 2026)

1. Q3 2026 intake compares README bullets, hashes, and metadata—receipts are how you prove they describe the same build.
2. Overnight CI without morning context breaks Asia-EU handoffs unless a machine-readable receipt survives the night.
3. RC freeze weeks need a paper trail when someone asks why build_id jumped—your seven-day RC challenge assumes receipts exist.

Direct answer: Drop BUILD_RECEIPT.json beside every cert-facing zip and append one row to upload_log.csv before you close the laptop.

Evening overview (four blocks)

Stop when a teammate (or future you) can open the zip and understand the build without Slack.

Block 1 — Folder placement

Align with taxonomy—do not invent parallel trees:

release-evidence/
  01-build/              # binaries you hash
  05-operations/
    BUILD_RECEIPT.template.json
    upload_log.csv
    receipts/              # archived copies per build_id

Why 05-operations/? Partners rarely need your internal receipts folder, but you need a stable place that Friday Block 5 can spot-check.

Copy the template once; archive finalized receipts into receipts/{build_id}.json after each upload.

Block 2 — BUILD_RECEIPT.template.json

Start minimal. Expand only when a partner asks.

{
  "receipt_version": "1.0",
  "build_id": "REPLACE_ME",
  "game_codename": "REPLACE_ME",
  "platform": "win64",
  "channel": "steam",
  "git": {
    "remote": "origin",
    "branch": "main",
    "commit": "0000000000000000000000000000000000000000",
    "dirty": false
  },
  "ci": {
    "system": "manual",
    "job_url": "",
    "built_at_utc": "2026-05-18T00:00:00Z"
  },
  "artifacts": {
    "primary_zip": "",
    "manifest_path": "MANIFEST.json",
    "sha256_sidecar": "SHA256SUMS.txt"
  },
  "human_signoff": {
    "name": "GamineAI Team",
    "role": "release_owner",
    "signed_at_utc": ""
  }
}

Field rules for beginners:

• build_id — same pattern as partner ZIP naming: {studio}_{game}_{channel}_{short_hash}_{date_utc}.
• git.dirty — run git status --porcelain; if anything prints, set true and fix before partner upload unless the diff is documented.
• ci.system — use "manual" until GitHub Actions or similar writes receipts for you.
• human_signoff — one named role; rotate names in the log, not in the schema.

Commit the template to Git. Receipts inside zips can diverge slightly per build; the template should not.

Block 3 — Generate tonight’s receipt

Step A — Pick commit

git rev-parse HEAD
git status --porcelain

Paste the full hash into git.commit. If porcelain is non-empty, stop and either commit or stash—do not ship dirty builds to partners without a note in KNOWN_ISSUES.md.

Step B — Fill build_id

Example: northlake_riftbound_steam_a1b2c3d_cert_20260518

Use the short hash from the first seven characters of the commit only if your team already standardized that—consistency beats cleverness.

Step C — Timestamp in UTC

date -u +"%Y-%m-%dT%H:%M:%SZ"

Never use local time without a timezone offset in JSON—reviewers compare across regions.

Step D — Copy into zip root

Save as BUILD_RECEIPT.json at the partner zip root (next to PARTNER_README.md). Archive a duplicate:

release-evidence/05-operations/receipts/northlake_riftbound_steam_a1b2c3d_cert_20260518.json

Success check: jq .build_id BUILD_RECEIPT.json prints the same string as your planned zip filename.

Block 4 — upload_log.csv

Create the file with a header row once:

uploaded_at_utc,build_id,portal,zip_filename,portal_ticket,result,notes

After each upload:

2026-05-18T22:10:00Z,northlake_riftbound_steam_a1b2c3d_cert_20260518,partner_cert,northlake_riftbound_steam_a1b2c3d_cert_20260518.zip,TCK-88421,submitted,first Q3 packet

Columns explained:

Store the CSV only in 05-operations/ unless partners request it inside the zip. Link from README bullet 7: “Upload history: see 05_ops/upload_log.csv in internal evidence mirror.”

Pair receipts with SHA256 (do not skip)

A receipt without hashes describes intent, not files. After you create BUILD_RECEIPT.json, run the cold-validation drill:

1. Generate SHA256SUMS.txt.
2. Add manifest_sha256 field to receipt (optional but recommended):

"integrity": {
  "manifest_sha256": "abc...",
  "sums_filename": "SHA256SUMS.txt",
  "cold_validated_at_utc": "",
  "cold_validator": ""
}

Fill cold_validated_at_utc only after a second machine passes—honesty matters more than speed.

Manual CI tonight, automation tomorrow

You do not need Actions on day one. Evening workflow:

1. Build locally or download CI artifact.
2. Copy into 01-build/.
3. Write receipt JSON by hand from git rev-parse.
4. Hash, zip, log upload.

Week two upgrade: a shell script that prints JSON to stdout:

#!/usr/bin/env bash
set -euo pipefail
COMMIT=$(git rev-parse HEAD)
DIRTY=$(test -z "$(git status --porcelain)" && echo false || echo true)
BUILD_ID="${1:?build_id required}"
cat <<EOF
{
  "receipt_version": "1.0",
  "build_id": "$BUILD_ID",
  "git": { "commit": "$COMMIT", "dirty": $DIRTY },
  "ci": { "system": "script", "built_at_utc": "$(date -u +%Y-%m-%dT%H:%M:%SZ)" }
}
EOF

Paste output into the full template until you trust automation to merge fields.

Common mistakes (read before upload night)

1. Receipt inside zip but not archived in 05-operations/receipts/ — You will overwrite the only copy on the next export.
2. build_id in receipt ≠ zip filename — Partners search tickets by filename.
3. Local timestamps without Z — Converts badly in spreadsheets.
4. Empty human_signoff — Receipts without a role look auto-generated and untrusted.
5. Logging upload before cold validation — Log submitted only after hashes pass on a second machine.
6. Reusing receipt JSON across resubmissions — Bump build_id when bytes change.
7. Storing secrets in receipt — API keys do not belong in JSON partners download.

Beginner quick start (absolute minimum)

If you only do three things tonight:

1. Create upload_log.csv with the header row.
2. Write one BUILD_RECEIPT.json for the build on your desk.
3. Add a README line: “Build identity: see BUILD_RECEIPT.json.”

That alone beats 80% of first-time partner packets.

Pro tips for micro-studios

• Mirror receipt build_id in your Steam playtest branch name when possible—fewer translation errors.
• During mock audit, score dimension 2 zero if receipts are missing—forces the habit early.
• Keep a RECEIPT_DIFF.md when resubmitting—three lines: old id, new id, what changed.
• Use CSV UTF-8 without Excel’s smart quotes—open in a real editor.
• Tie receipts to two-storefront channels with separate rows, not separate columns in one row.

Handoff to another timezone

When someone else uploads while you sleep, they append to upload_log.csv and must not edit your receipt in place. Pattern from Asia-EU handoff:

00-handoff/outbox/HANDOFF_NOTE.md  → points at build_id + receipt path

The note is human; the receipt is machine truth.

Worked example (fictional)

Scenario: Solo dev ships northlake_riftbound_steam_a1b2c3d_cert_20260518.zip.

1. Commit 9f3a… on main, clean tree.
2. Receipt lists build_id, commit, UTC build time, human_signoff filled.
3. SHA256 sidecar generated; cold laptop passes.
4. Upload to partner portal; ticket TCK-88421.
5. CSV row appended with result=submitted.
6. Friday Block 5 spot-check confirms receipt archived under receipts/.

Partner asks Wednesday about hash mismatch—you open CSV, find TCK-88421, open archived receipt, diff against resubmission. No archaeology in Discord.

When receipts are not enough

Escalate when partners require:

• Hardware security module signing attestations
• Console-specific certification IDs
• Legal data-processing agreements outside your game repo

Those get separate PDFs—do not stuff contracts into BUILD_RECEIPT.json.

Extending the schema later

Add keys only with version bumps:

"receipt_version": "1.1",
"extensions": {
  "deck_verified_build": false,
  "ai_disclosure_packet": "04_ai/disclosure_matrix.csv"
}

Document new keys in release-evidence/README.md so parsers do not surprise you.

Integration with publisher diligence

Publisher diligence often asks for the same traceability. Reuse receipts—do not fork BUILD_RECEIPT_publisher.json unless contracts diverge.

PowerShell path (Windows-first teams)

If your evening build happens on Windows, the same pipeline applies—only the commands change.

# Commit hash
git rev-parse HEAD
git status --porcelain

# UTC timestamp
(Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")

# Quick dirty flag
if (git status --porcelain) { $dirty = $true } else { $dirty = $false }

Write JSON in VS Code with the JSON language mode so trailing commas fail fast. Avoid generating receipts inside Word or Google Docs—smart quotes break parsers.

When you hash, prefer Get-FileHash -Algorithm SHA256 and lowercase the hex before pasting into MANIFEST.json. The cold-validation post shows the full diff workflow.

Receipt vs MANIFEST vs README (do not merge them)

Collapsing all four into one README is how teams get yellow flags on resubmission. Keep roles separate even if one person wears every hat.

Resubmission without losing history

Partners return “please resubmit with consistent labels.” Your log should tell the story:

1. Leave the old CSV row—change result to superseded in notes or add a new row.
2. New build_id in receipt and zip name.
3. RESUBMISSION_NOTE.md at zip root (three lines).
4. Archive old receipt in receipts/—never delete.

Auditors compare archives. Deleting the first receipt looks like you are hiding a failed hash, even when the failure was an honest typo.

Spreadsheet habits that survive audits

upload_log.csv is not a fancy database—it is an audit trail.

• Open with a text editor when editing; use Excel only for read-only views.
• Never merge cells.
• Keep one portal per row—multi-portal uploads get multi-row entries with the same build_id if bytes are identical, different rows if zips differ.
• Add a reviewer_reply_at_utc column when you graduate from beginner mode—optional but saves email archaeology.

Export a PDF snapshot monthly into 05-operations/reports/ if your publisher asks for “upload history.” CSV remains source of truth.

Weekend extension ladder (after evening one)

Stop when automation writes the same fields you would type by hand—automation should not add secret fields you cannot explain.

AI disclosure and receipts

If you run the seven-day AI disclosure challenge, add optional receipt fields:

"extensions": {
  "ai_disclosure_version": "1.3",
  "ai_annex_paths": ["04_ai/disclosure_matrix.csv"]
}

Only add paths that exist in the zip you hash. Empty annex claims fail faster than missing marketing GIFs.

Save systems and receipt metadata

Games with serialization changes should note schema version in the receipt when nightly builds touch saves—see save fuzz resources for testing discipline. One line in extensions.save_schema_version prevents “which build corrupted this save?” threads during playtest.

Operating review hook

Teams using four-Friday operating review can add Block 3 question: “Did every upload this week append a CSV row and archive a receipt?” One minute, high leverage.

Production-stack bookmarks (honest next steps)

After this evening pipeline, bookmark these in order:

1. Release-evidence folder taxonomy — if you skipped it.
2. SHA256 cold-validation drill — same week as first receipt.
3. Partner ZIP naming — before first real upload.
4. Q3 submission intake templates — copy folder skeletons, not philosophy.
5. Mock audit tabletop — score yourself before portals do.

None replace receipts—they assume receipts exist.

Security and privacy (practical)

• Receipts may include ci.job_url—ensure URLs are not secret-signed tokens with write access.
• Do not log portal passwords in notes.
• If receipts contain contractor emails, redact in copies sent externally—keep full CSV internal.

FAQ alignment (search snippets)

What is BUILD_RECEIPT.json? A small JSON file that records which Git commit and UTC window produced a partner-facing zip, who signed off, and how it links to hash sidecars.

Do I need CI? No. Manual receipts are valid if honest and paired with SHA256 validation.

How is this different from MANIFEST.json? Manifest lists files and hashes; receipt lists provenance and humans. Ship both.

ninety-second troubleshooting

Key takeaways

• BUILD_RECEIPT.json answers “which commit is this zip?” for Q3 2026 partner and publisher reviews.
• upload_log.csv answers “when did we upload, and what ticket id?” without searching email.
• One evening is enough for templates; five minutes sustains the habit per release.
• Always pair receipts with SHA256 cold validation.
• Archive receipts under 05-operations/receipts/—never rely on the zip as the only copy.
• Use UTC everywhere; mark git.dirty honestly.
• Align build_id with partner ZIP naming.
• Handoffs need a note pointing at build_id, not a rewritten receipt.

FAQ

Can I use BUILD_RECEIPT.md instead of JSON?

Yes for solo use, but JSON parses cleanly in scripts and partner tooling. Start JSON if you expect automation within a month.

Should the receipt be inside the partner zip?

Yes at zip root for cert packets. Keep an archived copy in 05-operations/receipts/.

What if I ship from itch.io and Steam?

Two rows in upload_log.csv, two receipts (or one receipt with two artifacts entries)—never one ambiguous row.

Does this replace Steam build IDs?

No. Steam depot IDs stay in Steamworks. Receipts are for your evidence chain.

How does this relate to the mock audit?

Dimension 2 (build integrity) and dimension 6 (ops traceability) both improve when receipts and logs exist before the tabletop.

Should I version-control upload_log.csv?

Yes. Commit after each upload night so Git history backs the CSV. If you fear merge conflicts, append-only discipline keeps diffs readable.

What if my game has no Git yet?

Initialize Git before your first partner packet—even a single-branch repo beats “folder copy final FINAL.” Receipts without commits are weak evidence.

Glossary (plain language)

Portal self-download sanity check

After upload, when portals allow self-download:

1. Download the file the portal claims to store.
2. Re-hash and compare to your archived SHA256SUMS.txt.
3. Append CSV notes: self_download_hash_ok=true.

If hashes fail, open a ticket before reviewers do—log the ticket id in the same row.

Checklist card (print or pin in 05-operations/)

[ ] git commit recorded in receipt (full hash)
[ ] git.dirty is false OR documented in KNOWN_ISSUES.md
[ ] build_id matches planned zip filename
[ ] BUILD_RECEIPT.json at zip root + archived under receipts/
[ ] SHA256SUMS.txt matches MANIFEST.json paths
[ ] cold validation pass logged (second machine)
[ ] upload_log.csv row appended with portal_ticket
[ ] PARTNER_README bullet references receipt filename
[ ] HANDOFF_NOTE updated if another timezone uploads

Read the card aloud once before zipping. Verbalizing catches skipped steps better than silent checkbox fatigue.

Pairing with engine-specific beginner posts

If you are also learning an engine pipeline this month, receipts are orthogonal to engine tutorials—they attach after the build exists:

• Godot teams: finish floor load coordinator first, then receipt the export you actually upload.
• Unity teams: after Input preflight, receipt the same build_id you hash for Deck retest evidence.

The receipt does not care which engine produced the binary; it cares that your story about the binary is consistent everywhere partners look.

Honest limits

This pipeline does not:

• Replace legal review for AI or privacy claims
• Automate Steam depot configuration
• Guarantee cert approval

It guarantees you can explain what you shipped—a prerequisite for everything else in Q3 2026.

Conclusion

You do not need a release-engineering team to leave a trail. BUILD_RECEIPT.json plus upload_log.csv are the beginner spine that makes hash drills and ZIP naming defensible when someone asks hard questions in Q3 2026.

Block one evening this week, write tonight’s receipt before the next upload, and log the portal ticket the moment the progress bar finishes. Future you—and your partner in another timezone—will open a folder instead of scrolling chat.