docs: combined orchestrator + CLI + Unity-logs documentation updates (May 2026)#569
Merged
Conversation
…lessons
Adds two new sections to the orchestrator caching guide.
"Canonical Cache + Overlay (Advanced)" -- documents the new opt-in
`localCacheMode: canonical-overlay` value introduced in
game-ci/orchestrator. Covers:
* When to use it (multiple self-hosted runners on the same physical
host with multi-GB Library folders)
* Architecture (canonical store + per-runner hardlink overlay,
atomic-rename publish, SHA-versioned with `latest` pointer)
* Hardlink safety contract (write-temp-then-rename invariant; per-
subdirectory classifier table targeting Unity Library structure)
* Configuration example
* Sub-second hydration via `cacheMaterialize: prepared`
* Failure modes table (orphan staging cleanup, prepared-overlay
cancel-safety, missing-canonical recovery, sentinel mismatch
discard)
* Cross-platform behaviour table (NTFS/ReFS/ext4/xfs/btrfs/zfs/APFS/
Docker/cross-volume) with graceful fallback policy
* Six stated limitations (single-host topology, NTFS/ext4/xfs needed
for full benefit, junction safety on PowerShell, 1023-link NTFS
limit, modify-in-place propagation, multi-GB scale tested only
on NTFS)
* Performance characteristics table (eager 15-30 s, with junctions
2-8 s, prepared overlay < 1 s)
* Pointer to future strategies in the taxonomy (reflink-overlay,
bind-mount, nfs-passthrough, runner-affinity)
"Self-Hosted Operational Lessons" -- four lessons applicable to any
long-lived self-hosted runner that ephemeral runners never encounter:
* `PackageCache` subtree corruption from cross-runner restore --
detect-and-quarantine pattern for orphan-meta directories
* PowerShell forward-reference bug -- function calls before
definition silently fail in non-strict mode and downstream errors
surface as the failure
* GitHub Actions runner `_runner_file_commands` race -- concurrent
`core.setOutput` from fan-out steps races on the shared runner-temp
file; serialise output-emitting steps
* Path-filter on the workflow entrypoint -- `paths-ignore` for
`docs/**`, `*.md`, etc. to skip Unity CI on docs-only pushes
Inputs Reference table extended with the six new orchestrator-PR
inputs (`localCacheMode` enum extension, `canonicalCacheRoot`,
`canonicalCacheClassifier`, `canonicalCacheVersionRetention`,
`cacheMaterialize`, `cacheSentinelCanary`).
Pairs with `game-ci/orchestrator` PR (feat/canonical-cache-overlay
branch).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents the Orchestrator's collectUnityLogs / streamUnityLogs flags, including: - Quick-start GHA snippet with artifact upload - Full table of categories (Editor.log, licensing, audit, services-config, Hub logs, crash dumps, build report, bee_backend, Player.log, IL2CPP, project version, package manifest, macOS crash, Windows event log, license file) - Per-platform path resolution table (Linux / macOS / Windows) - Live log streaming behaviour and per-file byte cap - Action inputs and outputs (unityLogsPath, unityLogsManifest) - Sensitive-files guidance for license-file category - Multi-engine note pointing to engine-plugins doc Cross-links from failures-and-diagnostics and common-issues so users hitting the "Unity support wants logs" path land on the new page. Refs: game-ci/unity-builder#740 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Most gamedev projects keep their custom Unity editor images private to one job. Reframe the GitHub Actions example so the no-registry, build-and-use-in-same-job path is the headline, with honest guidance on rebuild cost (15-30 min per run on hosted runners) and a table of caching options (self-hosted runner, push-once, buildx + GHA cache). GHCR push remains documented as the cross-workflow option. Refs game-ci/cli#45. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents the no-prior-opt-in workflow: SSH into a self-hosted runner after a failing job, run `game-ci orchestrate --providerStrategy local --collectUnityLogs` and get the same diagnostic bundle without editing the workflow or re-running the build. Calls out the three concrete incident-response use cases this unlocks (overnight failure / locked workflow / live hang debugging) and references the upcoming remote `game-ci logs pull` follow-up command. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a "Convenient API" section to the Unity Log Collection page documenting the new game-ci logs subcommand group (collect, tail, plus reserved pull/fetch) and the Logs programmatic facade exported from @game-ci/orchestrator. Shows both end-to-end build flows (--collectUnityLogs) and one-shot ad-hoc usage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fixes the Code formatting CI check on the docs PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
To continue reviewing without waiting, purchase usage credits in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
|
Visit the preview URL for this PR (updated for commit 06a918a): https://game-ci-5559f--pr569-docs-combined-may-20-uijgtg47.web.app (expires Thu, 14 May 2026 16:37:03 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: 1f0574f15f83e11bfc148eae8646486a6d0e078b |
This was referenced May 7, 2026
2 tasks
webbertakken
approved these changes
May 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Combines four open documentation PRs onto a single branch so they ship as one set:
hotfix/remove-cli-remote-build-conflict— removes leftover conflict markers fromdocs/03-github-cli/03-remote-builds.mdxdocs/build-unity-image-discovery— surfaces thebuild-unity-imagecustom-image flow across the Docker docs (01-docker-images.mdx,03-customize-docker-images.mdx,05-custom-images.mdx)docs/canonical-cache-and-self-hosted-lessons— canonical cache overlay strategy and self-hosted lessons in03-github-orchestrator/07-advanced-topics/01-caching.mdxdocs/unity-log-collection— Unity diagnostic log collection feature documentation: new22-unity-log-collection.mdxadvanced-topics page + cross-links from21-failures-and-diagnostics.mdxand09-troubleshooting/common-issues.mdx(refs Simple way to fetch logs unity-builder#740)The four branches are independent — no overlapping files, no merge conflicts. Each is preserved as a merge commit in this branch's history so reviewers can drill into the original work.
Why combine
These four small docs PRs all relate to the same May 2026 wave of orchestrator/CLI feature shipping (build-unity-image, canonical cache, Unity log collection) and reviewing them as one keeps the navigation/cross-link story coherent (e.g. the new Unity Log Collection page references the canonical cache / build reliability / engine-plugins pages that ship alongside).
What this PR replaces
After merge, please close #565, #566, #567, #568 with a "superseded by #NNN" note pointing back here.
Test plan
yarn buildDocusaurus locally renders all four sets of changes without broken links/docs/github-orchestrator/advanced-topics/unity-log-collectionroute resolves21-failures-and-diagnostics.mdxandcommon-issues.mdxresolve🤖 Generated with Claude Code