Orchestrator: LTS 2.0.0 by frostebite · Pull Request #541 · game-ci/documentation

frostebite · 2026-03-05T23:22:59Z

Summary

Combined documentation update for the orchestrator LTS 2.0.0 release. Updated to reflect the standalone @game-ci/orchestrator package architecture.

Key changes

Orchestrator introduction updated with standalone package callout
CLI docs reference @game-ci/orchestrator package (not unity-builder)
Provider documentation: AWS, K8s, Local Docker, GCP Cloud Run, Azure ACI
CLI provider protocol and dynamic provider loading
Build services: submodule profiles, local caching, LFS agents, git hooks
Load balancing, secrets, storage, architecture docs
Test workflow engine, hot runner protocol, build output system
Massive projects and monorepo support guides
Dedicated AWS and Kubernetes example pages with copy-paste workflows

Consolidates

docs(orchestrator): comprehensive documentation update for LTS version #532 — docs(orchestrator): comprehensive documentation update for LTS version
docs(providers): GCP Cloud Run and Azure ACI #533 — docs(providers): GCP Cloud Run and Azure ACI
docs(orchestrator): QoL build services — CLI providers, caching, LFS, hooks #535 — docs(orchestrator): QoL build services — CLI providers, caching, LFS, hooks
docs(orchestrator): built-in load balancing across providers #536 — docs(orchestrator): built-in load balancing across providers
docs(secrets): premade secret sources documentation #537 — docs(secrets): premade secret sources documentation
docs(orchestrator): next-gen features and advanced topics #538 — docs(orchestrator): next-gen features and advanced topics
docs(cli): game-ci CLI documentation #540 — docs(cli): game-ci CLI documentation
docs: Next-Gen Features — Combined Documentation #542 — docs: Next-Gen Features — Combined Documentation (closed, superseded by this PR)

Also incorporates content from closed unity-builder PRs:

docs(orchestrator): provider plugins, build services, and cloud providers unity-builder#779, #780, #781, #782

Standalone architecture

The orchestrator is now a standalone package at game-ci/orchestrator. When installed, unity-builder automatically loads it via the plugin interface.

Cross-references

Orchestrator extraction: Orchestrator Extraction — Remove Orchestrator Code, Add Plugin Loader unity-builder#819
Orchestrator repo: https://github.com/game-ci/orchestrator

Test plan

Verify Docusaurus builds successfully
Verify all internal doc links resolve
Verify code examples reference correct packages

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Major overhaul of GitHub Orchestrator docs: consolidated overview, new API reference, job lifecycle, extensive examples, and expanded CLI guides.
- New provider docs: AWS, Kubernetes, GCP Cloud Run (experimental), Azure ACI (experimental), Local, Local Docker, GitHub/GitLab dispatch, Remote PowerShell, Ansible, custom/community providers.
- Expanded advanced topics: caching, retained workspaces, garbage collection, hooks, secrets, logging, load balancing, hot runners, storage, monorepo support, large-project guidance.

Document how to use custom providers via GitHub repos, NPM packages, or local paths. Covers the ProviderInterface, supported source formats, caching behavior, and a full example implementation. Also updates the API reference to mention custom providers under providerStrategy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Restructure providers into dedicated section with overview, custom providers, community providers (with GitHub edit link), and GitHub/GitLab integration pages - Rewrite API reference with proper tables, all missing parameters (orchestratorRepoName, githubOwner, allowDirtyBuild, postBuildSteps, preBuildSteps, customHookFiles, customCommandHooks, useCleanupCron), and environment variables (AWS_FORCE_PROVIDER, PURGE_REMOTE_BUILDER_CACHE, ORCHESTRATOR_AWS_STACK_WAIT_TIME, GIT_PRIVATE_TOKEN) - Document premade rclone hooks and Steam deployment hooks - Add S3/rclone workspace locking documentation - Tighten language across all pages for clarity - Add ASCII diagrams to introduction, caching, logging, and config override - Add tasteful emoji to section headers - Rename "Game-CI vs Orchestrator" to "Standard Game-CI vs Orchestrator Mode" - Remove outdated Deno section from command line docs - Improve examples with proper tables, workflow snippets, and cross-links Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Content already merged into the providers section at 07-providers/05-gitlab-integration.mdx Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…e cross-linking - Promote Providers from Advanced Topics to top-level section (05-providers/) with dedicated pages for AWS, Kubernetes, Local Docker, Local, Custom, Community, GitHub Integration, and GitLab Integration - Move Secrets out of Advanced Topics to top-level (06-secrets.mdx) - Rename custom-hooks to hooks throughout - Remove all WIP/preview/release-status notices (project is stable) - Fix floating {/* */} comment symbols in community-providers (use code block template) - Update ASCII diagram in Game-CI vs Orchestrator to show CLI/any CI dispatch - Add sidebar_label frontmatter for Game-CI vs Orchestrator page - Add comprehensive cross-linking across all orchestrator docs: - Introduction links to providers, hooks, getting started, platforms - API Reference links to caching, hooks, providers, configuration override - Provider pages link to caching, hooks, API Reference sections - Getting Started links to provider setup guides and secrets - GitHub Integration links to API Reference for parameters and modes - Advanced Topics pages cross-reference each other and API Reference - Fix all broken links from old directory structure - Delete old directories (examples/github-examples, advanced-topics/providers) - Run Prettier on all files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Merge configuration-override.mdx content into secrets.mdx as a section - Delete standalone configuration-override page - Rename "Configuration Override" to "Pull Secrets" in API reference - Update all cross-links (command-line, GitLab integration, API reference) - Fix logging: "Orchestrator job (Fargate task)" instead of "Fargate tasks" Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Link to container-hooks page instead of the hooks directory. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Complete workflow examples for every provider and common patterns: - Minimal workflow, AWS Fargate, Kubernetes, Local Docker - Async mode with GitHub Checks - Scheduled garbage collection - Multi-platform matrix builds - Retained workspaces for faster rebuilds - Container hooks (S3 upload + Steam deploy) - Required secrets tables and cross-links to all relevant docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Equalize box widths and arrow spacing for consistent rendering. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ned workspaces - Custom Providers: plugin loading flow (source → fetch → ProviderInterface) - GitHub Integration: async mode lifecycle (dispatch → return → Check updates) - Retained Workspaces: workspace locking across concurrent builds Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…roviders overview - Container Hooks: build pipeline with pre/post hook execution points - Garbage Collection: resource lifecycle (normal cleanup vs stale → GC) - AWS: CloudFormation resource stack (ECS, S3, CloudWatch, Kinesis) - Providers Overview: decision flowchart for choosing a provider Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Shows each provider side-by-side with its key trait instead of a decision flowchart. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Set Advanced Topics position to 7.0 so it renders after Secrets (position 6 from filename). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Update title and all cross-references across container hooks, command hooks, and GitHub Actions examples. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Rename premade-container-jobs.mdx to built-in-hooks.mdx (fixes URL slug) - Update all links from premade-container-jobs to built-in-hooks - Rename "Pre-built Hooks" section header to "Built-In Hooks" - Move Custom Job from hooks/ to advanced-topics/ (it's not a hook) - Rename "Custom Jobs" to "Custom Job" (singular) - Update API reference link to advanced-topics/custom-job - Fix numbering conflicts in advanced-topics - Fix retained workspace diagram alignment (remove emoji, align box walls) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove emoji characters from diagrams (variable width across platforms makes alignment impossible). Fix box wall alignment, arrow connections, and consistent spacing in all 11 diagrams: - Introduction (architecture overview) - Caching (standard vs retained) - Providers overview (4-across comparison) - Container hooks (build pipeline) - GitHub integration (async mode lifecycle) - AWS (CloudFormation resource stack) - Secrets (pull flow) - Logging (log pipeline) - Garbage collection (resource lifecycle) - Custom providers (plugin loading) - Retained workspaces (already fixed) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Documents how to route builds across multiple providers using GitHub Actions scripting: platform-based routing, branch-based routing, runner availability fallback, weighted distribution, and async mode integration. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Storage page: documents project files, build output, caches, S3 and rclone backends, LZ4 compression, workspace locking, large packages, and container file system layout - Architecture page: describes build lifecycle, core components, provider system, workflow composition, hook system, configuration resolution, remote client, CLI modes, and source code map - Caching page: add Build Caching section explaining automatic build output caching based on cache key Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The box previously said "GitHub Actions" which contradicted the "Your Machine / CI" header. Now lists GitHub Actions, GitLab CI, CLI, etc. to reflect that Orchestrator works from any entry point. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…, hooks Adds a new advanced topics page documenting orchestrator build services: - Submodule profiles (YAML, glob patterns, variant overlays) - Local build caching (Library + LFS filesystem cache) - Custom LFS transfer agents (elastic-git-storage, etc.) - Git hooks (lefthook/husky detection, skip lists) Related: game-ci/unity-builder#777 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Covers storage type comparison tables, inputs, examples, and cross-links to related providers. Both marked as experimental. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds a new page documenting the CLI provider protocol that lets users write orchestrator providers in any language (Go, Python, Rust, shell). Covers: invocation model, JSON stdin/stdout protocol, streaming output, subcommands with timeouts, shell example, CLI vs TypeScript comparison. Related: game-ci/unity-builder#777 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Documents the new fallbackProviderStrategy, runnerCheckEnabled, runnerCheckLabels, and runnerCheckMinAvailable inputs. Adds comparison table for built-in vs manual fallback approaches. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Reframes page around intelligent provider routing with built-in API. Adds retry-on-alternate, provider init timeout, async mode integration, and decision table. Restructures manual scripting as secondary option. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ting examples Add two new script-based routing patterns: dispatching to an alternate workflow when self-hosted runners are busy, and using reusable workflows for shared build config with dynamic provider routing. Updated the comparison table with the new patterns. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Expand the Secrets page with premade source documentation (AWS Secrets Manager, AWS Parameter Store, GCP Secret Manager, Azure Key Vault, env), custom commands, YAML definitions, and migration from legacy inputPullCommand. Covers all five cloud providers and the env source. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Documents hashicorp-vault (KV v2), hashicorp-vault-kv1 (KV v1), and vault (shorthand alias). Covers VAULT_ADDR, VAULT_TOKEN, and VAULT_MOUNT configuration with examples for both KV versions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

New Jobs page explains the build lifecycle, job types (build, test, custom editor method, custom job, async), pre/post build phases, and execution by provider. Gives users a conceptual overview before diving into advanced topics. New LFS Agents page documents elastic-git-storage built-in support with auto-install, version pinning, multiple storage backends, and custom agent configuration. Renamed api-reference from 04 to 05 to accommodate the new Jobs page. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add documentation for two new orchestrator features: - Test Workflow Engine: YAML-based test suite definitions, taxonomy filters, structured results - Hot Runner Protocol: extensible runner registration, persistent editor providers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…pulling workaround Add troubleshooting entry for the Container Overrides 8192-byte limit that AWS ECS/Fargate users can hit with complex workflows. Document the connection between using secretSource/pullInputList and reducing the override payload size. Cross-link from AWS provider docs and secrets docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Show failure count (e.g., "15/15") next to failed build status icons. Add a reset button (admin-only) that calls the new resetFailedBuilds backend endpoint to clear inflated failure counts so the Ingeminator can retry them automatically. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…#548 The 8192 troubleshooting entry and build reset button UI changes are now in a separate PR (#548) targeting main. The orchestrator-specific docs (AWS provider troubleshooting section and secrets tip callout) remain here since those files only exist on this branch. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

This PR now only contains the reset button UI changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add 8192 troubleshooting entry and reset button for maxed-out builds - Add troubleshooting entry for the AWS ECS containerOverrides 8192-byte limit with explanation and secret-pulling workaround - Show failure count (e.g. "15/15") next to failed build status icons - Add admin-only reset button that calls resetFailedBuilds endpoint to clear inflated failure counts so the Ingeminator retries them Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * remove troubleshooting entry (moved to orchestrator LTS 2.0.0 PR #541) This PR now only contains the reset button UI changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com>

…clarification Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Note that the base "game-ci" stack is preserved - Remove mention of --garbageMaxAge (not actually wired in AWS provider) - Add caution admonition about no dry-run/confirmation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This reverts commit 66a738d.

Covers two approaches: - Sidecar (per-build): start/stop accelerator via container hooks, persist cache to S3 between builds - Persistent (shared): always-on EC2/ECS instance in same VPC Includes full hook YAML examples, workflow config, troubleshooting, and guidance on combining with Library caching. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Documents three new caching features: - cacheCheckpointInterval: periodic Library saves during build - cacheSaveOnFailure: trap-based partial save on OOM/crash - cacheRetentionDays: auto-purge old S3 entries Includes decision tables, Mermaid diagrams, and guidance on combining with Unity Accelerator for maximum resilience. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Shows three approaches: local tar + S3 upload, CLI cache-push, and one-time local-docker build to seed the cache. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

frostebite and others added 30 commits March 5, 2026 04:56

Remove old standalone GitLab pages from versioned docs

172ae89

Content already merged into the providers section at 07-providers/05-gitlab-integration.mdx Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix broken link: hooks directory has no index page

6f9667f

Link to container-hooks page instead of the hooks directory. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix ASCII diagram alignment in Game-CI vs Orchestrator

e9abe77

Equalize box widths and arrow spacing for consistent rendering. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace provider decision tree with simple 4-across comparison

db90cbc

Shows each provider side-by-side with its key trait instead of a decision flowchart. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix sidebar ordering: Secrets before Advanced Topics

07da84a

Set Advanced Topics position to 7.0 so it renders after Secrets (position 6 from filename). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename Premade Container Hooks to Built-In Hooks

557659d

Update title and all cross-references across container hooks, command hooks, and GitHub Actions examples. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix ASCII diagram alignment in load balancing page

7b370f1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs(providers): add GCP Cloud Run and Azure ACI provider documentation

2321c1e

Covers storage type comparison tables, inputs, examples, and cross-links to related providers. Both marked as experimental. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: add structured build output system page

ccb4a27

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

frostebite and others added 6 commits March 25, 2026 01:31

docs: rename AWS section from Limitations to Troubleshooting

e354106

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: use destructured meta variable to satisfy lint rule

d34729e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: restore 8192 troubleshooting entry for orchestrator LTS 2.0.0

299c33c

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

frostebite added a commit that referenced this pull request Mar 26, 2026

remove troubleshooting entry (moved to orchestrator LTS 2.0.0 PR #541)

6750c86

This PR now only contains the reset button UI changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

GabLeRoux reviewed Apr 17, 2026

View reviewed changes

Comment thread docs/03-github-orchestrator/01-introduction.mdx Outdated

Comment thread docs/03-github-orchestrator/01-introduction.mdx Outdated

GabLeRoux reviewed Apr 17, 2026

View reviewed changes

frostebite and others added 6 commits April 22, 2026 18:37

Update docs/03-github-orchestrator/01-introduction.mdx

d695a57

Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com>

Update docs/03-github-orchestrator/01-introduction.mdx

daed560

Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com>

Update docs/03-github-orchestrator/02-getting-started.mdx

3fd566f

Co-authored-by: Gabriel Le Breton <lebreton.gabriel@gmail.com>

docs: address Gabe's review — provider tabs, OIDC auth, SSO note, GC …

be45b07

…clarification Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Revert "docs: improve garbage-collect description with safety warning"

80689c2

This reverts commit 66a738d.

frostebite mentioned this pull request May 3, 2026

feat: implement garbage-collect for all providers game-ci/orchestrator#9

Merged

5 tasks

frostebite and others added 6 commits May 3, 2026 15:42

docs: add cache pre-warming examples to checkpointing guide

4907d24

Shows three approaches: local tar + S3 upload, CLI cache-push, and one-time local-docker build to seed the cache. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: align mermaid dependencies with lockfile

b54320d

Merge branch 'main' into release/lts-2.0.0

065a6de

fix: avoid mermaid policy-blocked dependencies

d70521c

frostebite enabled auto-merge (squash) May 3, 2026 15:43

webbertakken approved these changes May 3, 2026

View reviewed changes

frostebite merged commit ac839a4 into main May 3, 2026
9 checks passed

frostebite deleted the release/lts-2.0.0 branch May 3, 2026 15:58

This was referenced May 4, 2026

Improve Orchestrator docs structure and caching guidance #558

Merged

Document public CLI and clarify Orchestrator positioning #559

Merged

docs: clarify CLI command surfaces #561

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Orchestrator: LTS 2.0.0#541

Orchestrator: LTS 2.0.0#541
frostebite merged 86 commits intomainfrom
release/lts-2.0.0

frostebite commented Mar 5, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

frostebite commented Mar 5, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key changes

Consolidates

Standalone architecture

Cross-references

Test plan

Summary by CodeRabbit

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

frostebite commented Mar 5, 2026 •

edited by coderabbitai Bot

Loading