Orchestrator: LTS 2.0.0

[frostebite]

# Preview

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.

[frostebite]

Cross-references:

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

[github-actions]

Visit the preview URL for this PR (updated for commit 7ba5f93):

https://game-ci-5559f--pr541-release-lts-2-0-0-5mr6nsct.web.app

_{(expires Wed, 25 Mar 2026 13:51:28 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 1f0574f15f83e11bfc148eae8646486a6d0e078b}

[coderabbitai]

Actionable comments posted: 18

Note

Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.

🟡 Minor comments (14)

docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx-9-12 (1)

9-12: ⚠️ Potential issue | 🟡 Minor

Scope the resource comparison explicitly to GitHub-hosted runners.

This section starts out CI-platform agnostic, but the recommendation and ASCII diagram then assume GitHub-hosted limits (~14 GB disk, fixed resources). That will read incorrectly for GitLab/CircleCI users. Either scope the whole section to GitHub-hosted runners or change these references to generic “CI platform limits.”

Also applies to: 24-35

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx` around lines 9 -
12, The current paragraph starting "Game CI provides Docker images and GitHub
Actions for running Unity workflows..." and the following "**Best for:** Small
to medium projects..." assumes GitHub-hosted runner limits; either scope this
entire section to GitHub-hosted runners by adding an explicit qualifier like
"(for GitHub-hosted runners)" to the section heading and the opening sentence,
or remove GitHub-specific numbers and wording and replace them with generic
phrasing such as "typical CI platform limits" or "CI platform runner limits"
(e.g., change "~14 GB disk" and fixed resource references to "your CI platform's
disk and resource limits"); apply the same change to the later block that the
reviewer called out (the text around lines 24-35) so all comparisons are
consistently scoped or generalized.

docs/03-github-orchestrator/04-jobs.mdx-136-136 (1)

136-136: ⚠️ Potential issue | 🟡 Minor

Link text doesn't match target page.

The anchor text "elastic-git-storage" suggests a specific topic, but the link points to the general lfs-agents page. Consider either updating the link text to "LFS agents" for consistency, or using an anchor to link to a specific section if one exists.

-- Submodule initialization (if using [submodule profiles](advanced-topics/submodule-profiles))
-- Custom LFS agent configuration (e.g., [elastic-git-storage](advanced-topics/lfs-agents))
+- Submodule initialization (if using [submodule profiles](advanced-topics/submodule-profiles))
+- Custom LFS agent configuration (e.g., [LFS agents](advanced-topics/lfs-agents))

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/04-jobs.mdx` at line 136, The link anchor text
"elastic-git-storage" in docs/03-github-orchestrator/04-jobs.mdx doesn't match
the target page "advanced-topics/lfs-agents"; update the link so the display
text reads "LFS agents" to match the target, or change the href to point to a
specific section anchor on advanced-topics/lfs-agents (e.g., add
`#elastic-git-storage` if that section exists) so the link text and destination
align.

docs/03-github-orchestrator/07-advanced-topics/03-custom-job.mdx-18-19 (1)

18-19: ⚠️ Potential issue | 🟡 Minor

Avoid calling this cloud-only infrastructure.

customJob is documented elsewhere in this PR as running across multiple provider types, including Local Docker. Saying “cloud infrastructure” narrows the feature incorrectly; “Orchestrator-managed infrastructure” or “supported providers” would be more accurate.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/03-custom-job.mdx` around
lines 18 - 19, The phrase "cloud infrastructure" and the admonition to "Avoid
calling this cloud-only infrastructure" incorrectly narrows the scope of the
documented feature; update the text around the customJob description to refer to
"Orchestrator-managed infrastructure" or "supported providers" (and remove
"cloud-only") so it accurately reflects that customJob can run on multiple
provider types (including Local Docker); ensure the sentence mentioning
customJob explicitly uses the symbol name customJob and replaces "cloud
infrastructure" with one of the suggested alternatives.

docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx-19-24 (1)

19-24: ⚠️ Potential issue | 🟡 Minor

Clarify whether storage://... belongs to direct-input or storage-pull.

The strategy table says direct-input is inline/job-provided content and storage-pull is remote storage, but the example uses syncStrategy: direct-input with a storage://... URI. As written, it's not clear which strategy readers should actually set.

📝 Suggested doc tweak

 - uses: game-ci/unity-builder@v4
   with:
-    syncStrategy: direct-input
+    syncStrategy: storage-pull
     syncInputRef: storage://my-remote/inputs/changes.tar.lz4

If direct-input is intended to support storage URIs too, the strategy table should be updated to say that explicitly.

Also applies to: 47-52, 124-127

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx`
around lines 19 - 24, The table and example conflict over whether storage URIs
like storage://... belong to direct-input or storage-pull; decide which strategy
should accept storage URIs and make the docs consistent by either (A) stating in
the Strategy table that `direct-input` accepts inline content and storage URIs
(update the `direct-input` row) and adding a clarifying sentence where
`syncStrategy: direct-input` is shown (including the `storage://...` example),
or (B) changing the example that currently shows `syncStrategy: direct-input`
with a `storage://...` URI to use `syncStrategy: storage-pull` and ensure
surrounding text explains that `storage-pull` is for remote storage URIs; update
all occurrences cited (around lines 19-24, 47-52, 124-127) to match the chosen
behavior.

docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx-196-196 (1)

196-196: ⚠️ Potential issue | 🟡 Minor

Split the Azure reference out of this related link.

This bullet says "GCP Cloud Run and Azure ACI," but it only links to the GCP page. That makes the Azure docs harder to discover from here.

📝 Suggested doc tweak

-- [Cloud Providers](/docs/github-orchestrator/providers/gcp-cloud-run) — GCP Cloud Run and Azure ACI
+- [GCP Cloud Run](/docs/github-orchestrator/providers/gcp-cloud-run)
+- [Azure ACI](/docs/github-orchestrator/providers/azure-aci)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx` at line
196, The related-link entry currently reads "[Cloud
Providers](/docs/github-orchestrator/providers/gcp-cloud-run) — GCP Cloud Run
and Azure ACI" but only links to GCP; update this so GCP and Azure are separate
links: keep the GCP link text/URL ([Cloud Providers] or [GCP Cloud Run]
referencing /docs/github-orchestrator/providers/gcp-cloud-run) and add a second
link for Azure (e.g., [Azure ACI] pointing to the Azure provider doc like
/docs/github-orchestrator/providers/azure-aci or the correct Azure doc slug);
ensure the visible text lists both providers and each has its own accurate href
so Azure docs are discoverable.

docs/03-github-orchestrator/03-examples/02-github-actions.mdx-155-159 (1)

155-159: ⚠️ Potential issue | 🟡 Minor

Use a portable kubeconfig encoding command here.

base64 -w 0 is GNU-specific and fails on macOS/BSD systems. The -w flag is not available in BSD's base64 implementation, which uses -b instead. A portable alternative that works across all platforms:

📝 Suggested fix

-cat ~/.kube/config | base64 -w 0
+base64 < ~/.kube/config | tr -d '\n'

This approach removes line wrapping in a portable way by piping through tr -d '\n', eliminating the platform-specific rabbit hole.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx` around lines
155 - 159, Replace the GNU-specific use of "base64 -w 0" in the kubeconfig
encoding instruction with a portable approach: run base64 without the -w flag
and pipe its output through tr to delete newlines so the result is a
single-line, platform-independent base64 string; update the example text in the
docs/03-github-orchestrator/03-examples/02-github-actions.mdx snippet
accordingly so macOS/BSD and Linux users get the same behavior.

docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx-58-68 (1)

58-68: ⚠️ Potential issue | 🟡 Minor

Add builtClientPath to the run-field reference.

The built-client example uses builtClientPath, but the Run Fields table never defines it. A short row here would make it clear when the path is required and what it is relative to.

Also applies to: 141-145

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx`
around lines 58 - 68, Add a new row for the run field `builtClientPath` in the
Run Fields table: explain that `builtClientPath` is the filesystem path to the
built Unity client used when `builtClient: true`, note whether it should be
absolute or relative (e.g., relative to the repository root or workflow working
directory), and mention any default/required format and examples; update the
same table instance referenced later (the second occurrence at the other
location) so both places define `builtClientPath` consistently.

docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx-161-161 (1)

161-161: ⚠️ Potential issue | 🟡 Minor

Clarify whether gitlabProjectId expects a raw path or a URL-encoded path.

The examples above use my-group/unity-builds, but this reference row says path-based values should be URL-encoded (my-group%2Funity-builds). Please make the examples and the reference agree so readers know which format to pass.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx` at line
161, The docs disagree about the expected format for gitlabProjectId: update the
examples and the reference row for gitlabProjectId so they match (choose either
raw path like my-group/unity-builds or URL-encoded my-group%2Funity-builds) and
clearly state which format consumers must pass; ensure every occurrence of
gitlabProjectId in the GitLab CI dispatch docs (examples, parameter table, and
any sample payloads) is changed to the chosen format and add a short note
showing the alternative encoding if useful for URLs.

docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx-57-66 (1)

57-66: ⚠️ Potential issue | 🟡 Minor

Avoid @main in release docs.

Both workflow examples point readers at game-ci/unity-builder@main, while the rest of this doc set uses versioned refs. For LTS documentation, @main makes the examples non-reproducible and lets them drift immediately from the behavior described here.

Suggested doc update

- - uses: game-ci/unity-builder@main
+ - uses: game-ci/unity-builder@v4

Also applies to: 129-137

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx` around
lines 57 - 66, The docs use an unpinned action reference "uses:
game-ci/unity-builder@main" which should be replaced with a versioned ref to
ensure reproducibility; update every occurrence (including the instance at lines
~129-137) to a specific tag or release pin (e.g., a semver tag or commit SHA) so
examples in the GitLab CI dispatch snippet and the other workflow block no
longer reference `@main` but a stable version.

docs/03-github-orchestrator/05-providers/01-overview.mdx-22-34 (1)

22-34: ⚠️ Potential issue | 🟡 Minor

This overview omits provider strategies documented elsewhere in the same section.

This table/list reads as the authoritative provider index, but this PR also adds pages for gcp-cloud-run, azure-aci, and gitlab-ci. Readers starting here will miss supported providerStrategy values unless this page either includes them or explicitly scopes itself to a smaller subset.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/01-overview.mdx` around lines 22 -
34, The overview currently presents an authoritative list of providerStrategy
values but omits `gcp-cloud-run`, `azure-aci`, and `gitlab-ci`; either add rows
for these providerStrategy values to the provider table (`providerStrategy`
values: `gcp-cloud-run`, `azure-aci`, `gitlab-ci`) with short descriptions, or
explicitly mark the table as a partial subset and add a sentence linking to the
full provider index (or listing the missing providers) so readers won’t miss
supported strategies.

docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx-244-264 (1)

244-264: ⚠️ Potential issue | 🟡 Minor

Clarify that this table is describing internal modes, not the public game-ci CLI surface.

The shipped game-ci entrypoint currently registers yargs commands like build, activate, orchestrate, status, version, and update, while the decorator registry lives separately in src/model/cli/cli-functions-repository.ts. Without that distinction, this section reads like the public command list and conflicts with the actual binary entrypoint. (raw.githubusercontent.com)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx` around
lines 244 - 264, The CLI Modes table currently reads like the public game-ci CLI
surface; clarify it documents internal decorator-registered modes (the
`@CliFunction` registry) rather than user-facing yargs commands. Update the
paragraph heading and/or a short explanatory sentence above the table to state
these are internal mode names used by the CliFunction registry (see
cli-functions-repository.ts) and not the public commands exposed by the game-ci
entrypoint (which defines yargs commands like build, activate, orchestrate,
status, version, update in src/cli.ts). Keep the existing mode list but add that
distinction so readers know where to look for public CLI usage versus internal
mode handlers.

docs/03-github-orchestrator/05-api-reference.mdx-34-41 (1)

34-41: ⚠️ Potential issue | 🟡 Minor

The built-in provider list is incomplete here.

The standalone README and setupSelectedBuildPlatform() both enumerate additional built-ins, including gcp-cloud-run, azure-aci, remote-powershell, github-actions, gitlab-ci, and ansible. Leaving them out of the API reference makes several new provider pages in this PR look unsupported from the canonical parameter table. (raw.githubusercontent.com)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-api-reference.mdx` around lines 34 - 41, The
API reference table for the providerStrategy parameter is missing several
built-in provider names; update the
docs/03-github-orchestrator/05-api-reference.mdx table entry for
`providerStrategy` to list all built-in providers (at minimum: aws, k8s,
local-docker, local, gcp-cloud-run, azure-aci, remote-powershell,
github-actions, gitlab-ci, ansible) so it matches the implementations referenced
by setupSelectedBuildPlatform() and the orchestrator model; ensure the table
cell for `providerStrategy` mentions custom provider formats (GitHub URL, NPM
package, local path) exactly as currently worded and keep the rest of the
parameter rows unchanged.

docs/03-github-orchestrator/03-examples/04-kubernetes.mdx-163-171 (1)

163-171: ⚠️ Potential issue | 🟡 Minor

The base64 -w 0 flag is GNU-specific and won't work on macOS.

The -w 0 flag (disable line wrapping) is specific to GNU coreutils. On macOS, the equivalent is base64 without flags (no wrapping by default) or explicitly using base64 -b 0 in older versions.

Consider providing a cross-platform alternative or noting the platform difference.

📝 Suggested cross-platform command

 Base64-encode your kubeconfig file:

 ```bash
-cat ~/.kube/config | base64 -w 0
+# Linux (GNU coreutils)
+cat ~/.kube/config | base64 -w 0
+
+# macOS
+cat ~/.kube/config | base64

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/03-github-orchestrator/03-examples/04-kubernetes.mdx around lines 163 -
171, The docs currently instruct using the GNU-specific command base64 -w 0 to
encode the kubeconfig for the KUBE_CONFIG secret; update the text to provide a
cross-platform alternative by showing both the Linux (GNU coreutils) form
base64 -w 0 and the macOS form base64 (or base64 -b 0 for older macOS), or
add a short note explaining that macOS users should omit -w 0, and ensure the
example mentions storing the output as the GitHub Actions secret named
KUBE_CONFIG.

</details>

</blockquote></details>
<details>
<summary>docs/03-github-orchestrator/03-examples/04-kubernetes.mdx-99-109 (1)</summary><blockquote>

`99-109`: _⚠️ Potential issue_ | _🟡 Minor_

**Clarify that Orchestrator normalizes CPU/memory units for Kubernetes.**

The statement "Kubernetes uses the same unit format as AWS (`1024 = 1 vCPU`, memory in MB)" is technically incorrect for native Kubernetes, which uses millicores (e.g., `1000m = 1 CPU`) and memory in `Mi`/`Gi`. 

If Orchestrator normalizes these values internally, clarify that this is an **Orchestrator convention** that gets translated to Kubernetes-native units, rather than implying Kubernetes itself uses this format.



<details>
<summary>📝 Suggested clarification</summary>

```diff
 ### CPU and Memory

-Kubernetes uses the same unit format as AWS (`1024 = 1 vCPU`, memory in MB):
+Orchestrator uses a unified unit format across providers (`1024 = 1 vCPU`, memory in MB).
+These values are automatically converted to Kubernetes-native units (millicores and Mi/Gi):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/04-kubernetes.mdx` around lines 99 -
109, Update the "CPU and Memory" section and its table to state that the shown
units are an Orchestrator convention that are normalized and translated into
Kubernetes-native units (e.g., CPU -> millicores like 1000m = 1 CPU, memory ->
Mi/Gi) rather than implying Kubernetes itself uses "1024 = 1 vCPU" or MB;
explicitly mention "Orchestrator normalizes these values to Kubernetes
millicores and Mi/Gi" so readers understand the translation performed by
Orchestrator.

🧹 Nitpick comments (12)

docs/03-github-orchestrator/07-advanced-topics/04-garbage-collection.mdx (1)

32-38: Clarify why the GitHub Actions example still uses unity-builder.

Given the new standalone-package messaging, a short note here would help: this path runs through game-ci/unity-builder, which auto-loads @game-ci/orchestrator via the plugin interface. Without that, this example reads like Orchestrator is still bundled there.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/04-garbage-collection.mdx`
around lines 32 - 38, Add a short clarifying sentence after the example YAML
that explains why the action still references game-ci/unity-builder: state that
this workflow path uses game-ci/unity-builder which automatically loads
`@game-ci/orchestrator` via the plugin interface (so the example isn’t showing
Orchestrator bundled inside unity-builder), and mention you can instead call
`@game-ci/orchestrator` directly if using the standalone package; reference the
YAML keys shown (uses: game-ci/unity-builder@v4 and mode: garbage-collect) to
indicate where this behavior applies.

docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx (2)

46-56: Clarify the default behavior of gitAutoRecover.

The phrasing "the default when gitIntegrityCheck is on" (line 48) suggests a conditional default, but the inputs reference table (line 181) shows gitAutoRecover defaults to 'true' unconditionally. This could confuse users about what happens when gitIntegrityCheck is 'false' but gitAutoRecover is 'true' (both defaults).

Consider rephrasing to clarify that gitAutoRecover defaults to 'true' but only takes effect when gitIntegrityCheck is enabled:

-When `gitAutoRecover` is enabled (the default when `gitIntegrityCheck` is on) and corruption is
-detected, the service attempts recovery:
+When `gitAutoRecover` is enabled (default: `'true'`) and `gitIntegrityCheck` detects corruption,
+the service attempts recovery:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`
around lines 46 - 56, Reword the "Automatic Recovery" paragraph to state that
gitAutoRecover defaults to 'true' unconditionally but only has effect when
gitIntegrityCheck is enabled; specifically, update the sentence currently
reading "the default when `gitIntegrityCheck` is on" to something like
"gitAutoRecover defaults to 'true', but it only performs recovery actions when
`gitIntegrityCheck` is enabled" and ensure the subsequent steps still describe
the recovery sequence (remove corrupted `.git`, `git init`, checkout on next
step) and that the behavior is conditional on `gitIntegrityCheck` being active.

---

156-165: Consider updating example timestamps.

The archive layout example uses 2025 dates. While this doesn't affect functionality or understanding, updating to 2026 dates would keep the documentation current.

 /mnt/build-archives/
   StandaloneLinux64/
-    build-2025-01-15T10-30-00-000Z/
-    build-2025-01-16T14-22-00-000Z/
-    build-2025-01-17T09-15-00-000Z/
+    build-2026-01-15T10-30-00-000Z/
+    build-2026-01-16T14-22-00-000Z/
+    build-2026-01-17T09-15-00-000Z/
   StandaloneWindows64/
-    build-2025-01-15T10-45-00-000Z/
-    build-2025-01-16T14-35-00-000Z/
+    build-2026-01-15T10-45-00-000Z/
+    build-2026-01-16T14-35-00-000Z/

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`
around lines 156 - 165, Update the example archive timestamps in the snippet
under /mnt/build-archives/ (the entries for StandaloneLinux64 and
StandaloneWindows64) from 2025 to 2026 so the example shows current-year dates
(e.g., change build-2025-01-15T10-30-00-000Z to build-2026-01-15T10-30-00-000Z
and the other 2025 dates similarly).

docs/03-github-orchestrator/04-jobs.mdx (1)

185-189: Consider linking to a hooks overview page or adjusting the link text.

The "Hooks" link points specifically to container-hooks, but the section above (lines 169-170) mentions both container hooks and command hooks. Consider either:

• Linking to a hooks index/overview page if one exists
• Updating the link text to "Container Hooks" for accuracy

This is a minor navigation clarity improvement.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/04-jobs.mdx` around lines 185 - 189, The "Hooks"
link in the Next Steps list currently points to
advanced-topics/hooks/container-hooks but the docs mention both container hooks
and command hooks; update the link to either point to a hooks overview/index
(advanced-topics/hooks or equivalent) if that page exists, or change the link
text from "Hooks" to "Container Hooks" to accurately reflect the target (modify
the list item containing the link in the Next Steps block and the anchor text
accordingly).

docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx (1)

101-109: Clarify input format and consumption method for these YAML blocks.

The Post-Processing Pipelines section presents nested YAML structures (outputPipelines, customOutputTypes, etc.) without specifying whether they should be passed as multiline YAML strings to the with: input or stored in .game-ci/output-types.yml. This ambiguity risks copy-paste errors. Add a brief note—for example, "pass as a multiline YAML string to the outputPipelines input" or "store in .game-ci/output-types.yml"—to clarify the intended consumption method.

This applies to all similar code blocks in the section (lines 101–109, 116–124, 134–142, 152–168).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx`
around lines 101 - 109, Add a short clarifying sentence to each YAML example in
the Post-Processing Pipelines section (the blocks showing outputPipelines,
customOutputTypes, etc.) that explicitly states how the YAML should be provided:
either passed as a multiline YAML string to the action input (e.g., "pass as a
multiline YAML string to the outputPipelines input") or saved to the repo at
.game-ci/output-types.yml (e.g., "or store this configuration in
.game-ci/output-types.yml and reference it from the action"). Update the
examples at the affected locations (the blocks containing outputPipelines,
customOutputTypes and similar nested YAML snippets) to include this short note
so readers know whether to use the with: input or a repository file.

docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx (2)

74-83: Consider using a versioned tag instead of @main for consistency.

Other provider examples (e.g., Kubernetes, AWS) use @v4, but this example uses @main. For documentation consistency and stability, consider aligning with the versioned tag pattern unless there's a specific reason to track main.

Suggested change

-- uses: game-ci/unity-builder@main
+- uses: game-ci/unity-builder@v4

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx`
around lines 74 - 83, Replace the floating main ref on the GitHub Action usage
with a stable version tag: locate the uses: game-ci/unity-builder@main entry in
the GitHub Actions example and change it to a versioned tag (e.g., `@v4` or the
appropriate released tag) to match other provider examples and ensure
consistency and stability; update any accompanying text if it implies tracking
main.

---

137-146: Same observation: Consider using @v4 instead of @main.

For consistency with other provider documentation, consider using the versioned tag.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx`
around lines 137 - 146, The GitHub Actions step is pinned to the branch tag
"game-ci/unity-builder@main"; update that to the versioned tag
"game-ci/unity-builder@v4" for consistency with other docs. Locate the action
usage line (the "uses: game-ci/unity-builder@main" entry) in the GitHub Actions
example and change the tag to "@v4", keeping the rest of the step fields
(providerStrategy, targetPlatform, gitPrivateToken, githubActionsRepo,
githubActionsWorkflow, githubActionsToken, githubActionsRef) unchanged.

docs/03-github-orchestrator/05-providers/07-ansible.mdx (1)

49-58: Consider using versioned tag @v4 for consistency.

Same as other provider docs - this example uses @main while Kubernetes and AWS examples use @v4.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/07-ansible.mdx` around lines 49 -
58, Update the GitHub Action reference in the Ansible example to use the
versioned tag used elsewhere (change the uses value from
game-ci/unity-builder@main to game-ci/unity-builder@v4) so it matches Kubernetes
and AWS examples; verify the ansible example block (the uses line and
surrounding snippet: providerStrategy/ansible, ansibleInventory,
ansiblePlaybook, ansibleExtraVars, ansibleVaultPassword) still works with `@v4`
and adjust any option names if necessary to keep examples consistent across
provider docs.

docs/03-github-orchestrator/05-providers/04-local-docker.mdx (2)

1-1: Missing frontmatter for sidebar positioning.

Other provider documentation files include frontmatter with sidebar_position. Consider adding it for consistent navigation ordering.

Suggested addition

+---
+sidebar_position: 5
+---
+
 # Local Docker

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/04-local-docker.mdx` at line 1, Add
missing top-matter to the document so it appears correctly in the docs sidebar:
insert a YAML frontmatter block at the very top of the "Local Docker" doc
containing at least the title and a sidebar_position field (e.g., title: "Local
Docker" and sidebar_position: <number>) to match other provider docs; place the
block before the existing "# Local Docker" header and choose a numeric
sidebar_position consistent with sibling files to ensure correct ordering in the
sidebar.

---

23-28: CLI command inconsistency with other documentation.

The CLI example uses yarn run cli -m cli-build, but the CLI documentation in 08-cli/ uses game-ci build. Consider updating to the published CLI command for consistency, or add a note explaining this is for development usage.

Suggested change to align with CLI docs

 ### Command Line

 ```bash
-yarn run cli -m cli-build \
+game-ci build \
   --providerStrategy local-docker \
   --projectPath /path/to/your/project \
   --targetPlatform StandaloneLinux64

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/03-github-orchestrator/05-providers/04-local-docker.mdx around lines 23

• 28, Update the example CLI invocation so it matches the published CLI docs:
  replace the development command "yarn run cli -m cli-build" with the official
  "game-ci build" form (keeping the flags --providerStrategy, --projectPath,
  --targetPlatform intact) or, if you intend to show a dev-only invocation, add a
  short note clarifying that "yarn run cli -m cli-build" is for local development
  while "game-ci build" is the published command; adjust the example around the
  existing flags (--providerStrategy local-docker, --projectPath, --targetPlatform
  StandaloneLinux64) accordingly.

</details>

</blockquote></details>
<details>
<summary>docs/03-github-orchestrator/05-providers/06-custom-providers.mdx (1)</summary><blockquote>

`106-113`: **Use lowercase `number` for TypeScript primitive type.**

In TypeScript, `number` (lowercase) is the primitive type, while `Number` is the object wrapper. The interface should use the primitive type for consistency with TypeScript conventions.



<details>
<summary>Suggested fix</summary>

```diff
   garbageCollect(
     filter: string,
     previewOnly: boolean,
-    olderThan: Number,
+    olderThan: number,
     fullCache: boolean,
     baseDependencies: boolean,
   ): Promise<string>;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/06-custom-providers.mdx` around
lines 106 - 113, The garbageCollect method signature uses the boxed type Number;
update the parameter type to the TypeScript primitive by changing olderThan:
Number to olderThan: number in the garbageCollect declaration to match TS
conventions (modify the signature in the garbageCollect method
definition/interface).

docs/03-github-orchestrator/03-examples/03-aws.mdx (1)

151-166: Consider documenting Steam Guard handling for STEAM_PASSWORD.

The Steam deploy example passes STEAM_PASSWORD as an environment variable. While this is necessary, users should be aware that:

1. Steam accounts with Steam Guard may require additional handling (e.g., TOTP or pre-authenticated sentry files)
2. The password is exposed to the container environment

Consider adding a note or linking to Steam deployment documentation that covers authentication requirements.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/03-aws.mdx` around lines 151 - 166,
Add a short note under the "S3 Upload + Steam Deploy" example explaining that
STEAM_PASSWORD (and STEAM_USERNAME/STEAM_APPID) may require special handling for
Steam Guard/2FA: instruct users to store credentials in GitHub Secrets, mention
TOTP/Steam Guard and pre-authenticated sentry files as possible solutions, warn
that environment variables expose the password to the container, and optionally
link to Steam/SteamCMD authentication docs and the repo's steam-deploy-client
containerHookFiles guidance so users know where to configure sentry or
token-based auth.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx`:
- Around line 41-46: The Orchestrator column overgeneralizes maintenance and
cost; update the "**Maintenance**" and "**Cost model**" cells under the
"Orchestrator" column to qualify provider-dependent cases: replace "Fully
managed, no servers to maintain" with wording like "Often fully managed; may
require infra ownership for self-hosted/Kubernetes or cluster-backed
deployments" and replace "Pay per build (scales to zero)" with "Often
pay-per-build; some cluster-backed or always-on provider setups incur fixed
baseline costs" so the decision matrix reflects these exceptions.

In `@docs/03-github-orchestrator/02-getting-started.mdx`:
- Around line 6-8: Update the "Getting Started" docs to include where to
install/expose the standalone package `@game-ci/orchestrator` before using the
workflow examples: add a sentence and link in the paragraph that points to the
setup/install step (e.g., "Install and expose `@game-ci/orchestrator` via npm/yarn
and configure it in your repo — see Getting Started: Install Orchestrator"),
referencing the package name "@game-ci/orchestrator" and the "Getting Started"
install/setup section so readers know exactly where to perform the setup prior
to using the examples.

In `@docs/03-github-orchestrator/03-examples/01-command-line.mdx`:
- Around line 55-66: Update the cross-reference and example to point to the
current secrets docs and modern API: replace the broken anchor link
../secrets#-pulling-secrets-from-external-sources with the correct anchor in
docs/03-github-orchestrator/06-secrets.mdx (use the actual section anchor for
"Pull Secrets" or the top-level secrets page if no anchor exists) and change the
example flag from --inputPullCommand to the recommended --secretSource usage
(and corresponding variable names UNITY_EMAIL, UNITY_SERIAL, UNITY_PASSWORD) so
the sample matches the secrets page and avoids deprecated flow references.
- Around line 7-53: The examples currently point to cloning
game-ci/unity-builder and using "yarn run cli -m <mode>"; update Install to show
installing the published package (e.g., "yarn add -D `@game-ci/orchestrator`" or a
global install), change Usage to invoke the standalone CLI as "game-ci <command>
[options]" instead of "yarn run cli -m …", and replace the example invocations
that use "-m cli-build", "-m list-resources", "-m watch", and "-m
garbage-collect" with the corresponding top-level subcommands such as "game-ci
build", "game-ci status" (or "game-ci list-resources" if applicable), "game-ci
watch", and "game-ci garbage-collect" (keeping the same option names like
--projectPath, --providerStrategy, --targetPlatform, --gitPrivateToken unless
other flag names are documented); ensure the Help section shows "game-ci --help"
rather than "yarn run cli --help".

In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx`:
- Around line 135-146: The example enables an AWS S3 export hook via
containerHookFiles: aws-s3-upload-build but never shows how to authenticate to
AWS; update the docs to either remove the aws-s3-upload-build hook from the
Kubernetes example or add steps showing AWS credential setup (e.g., reference
using secrets like secrets.AWS_ACCESS_KEY_ID and secrets.AWS_SECRET_ACCESS_KEY
and/or calling the aws-actions/configure-aws-credentials action or setting AWS
env vars) and show where to inject those secrets into the workflow so the
aws-s3-upload-build hook can access S3.
- Around line 33-38: The workflow uses long-lived secrets AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY with aws-actions/configure-aws-credentials@v4; replace
this pattern by enabling GitHub OIDC: add a top-level permissions block granting
id-token: write and contents: read, and update the configure-aws-credentials
step to use role-to-assume instead of aws-access-key-id/aws-secret-access-key
(keep aws-region as before), referencing the IAM role ARN (role-to-assume) for
the GitHubActionsRole; make the same replacement for other identical occurrences
that use aws-actions/configure-aws-credentials@v4.

In `@docs/03-github-orchestrator/05-api-reference.mdx`:
- Around line 108-115: Remove the non-existent documented inputs `githubCheck`
and `asyncOrchestrator` from the GitHub Integration API table and any examples
in this page; update the table to only include real inputs (e.g., keep
`watchToEnd`) and replace references to GitHub Checks with the supported
`githubToken` / `unity-test-runner` flow. Search for and delete occurrences of
`githubCheck` and `asyncOrchestrator` in this document, update the description
row to reflect the actual inputs used by the published unity-builder action, and
adjust any examples that suggest setting those parameters to instead reference
`githubToken` or the standalone orchestrator note if applicable.

In `@docs/03-github-orchestrator/05-providers/05-local.mdx`:
- Around line 23-30: The command example is incorrect: it references a
non-existent script ("yarn run cli -m cli-build") and an unsupported mode
(providerStrategy/local). Update the docs to replace that CLI invocation with
the correct package command ("yarn game-ci" or "game-ci") and remove the
suggestion to use providerStrategy=local; instead state that the standalone
game-ci CLI does not support providerStrategy=local and advise users to run the
unity-builder on a self-hosted runner (game-ci/unity-builder) for local
execution, mentioning the cli-build/--targetPlatform usage only where applicable
to supported provider strategies.

In `@docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx`:
- Around line 37-41: Update the Setup and Security sections: replace the blanket
recommendation of Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*" with
guidance to specify explicit hostnames/IPs or target-specific entries (avoid
"*"), and add an alternative recommending WinRM over HTTPS (port 5986) with a
valid certificate for mutual authentication; in the Security note, qualify the
HTTP cleartext warning to say it applies to Basic authentication specifically
and explicitly mention that Negotiate (Kerberos/NTLM), CredSSP and similar
methods provide message-level protection over HTTP (5985), so HTTPS is primarily
required when using Basic or other cleartext auth or when host
authentication/encryption is needed.

In `@docs/03-github-orchestrator/05-providers/06b-cli-provider-protocol.mdx`:
- Around line 105-115: Update the timeout table to reflect the actual enforced
limits: change the `run-task` timeout from "No limit" to "2h" and change the
`watch-workflow` timeout from "No limit" to "1h"; also update the explanatory
sentence beneath the table to state that `run-task` is limited to 2 hours and
`watch-workflow` to 1 hour per the CLI provider implementation (referencing the
CLI provider's timeout enforcement for `run-task` and `watch-workflow`
subcommands).

In `@docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx`:
- Around line 8-27: Update the GitLab CI example to remove the legacy
game-ci/unity-builder clone and the old "yarn run cli -m cli-build ..."
invocation; replace it with the standalone `@game-ci/orchestrator` CLI usage and
the current flag style (use the CLI package instead of cloning
`game-ci/unity-builder`, and replace the command string `yarn run cli -m
cli-build --projectPath $CI_PROJECT_DIR --providerStrategy aws --gitPrivateToken
$GIT_TOKEN` with the modern orchestrator CLI invocation documented elsewhere in
this PR, using the current flag names/format for project path, provider, and
token).

In `@docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx`:
- Around line 68-69: The table row for the configuration key `gcpDiskSizeGb`
shows an invalid default of `100` for the in-memory volume (the prose above
limits in-memory to 32 GiB); update the table so the default value for
`gcpDiskSizeGb` matches the documented in-memory cap (e.g., change the default
from `100` to `32` and ensure the description still notes this is the in-memory
volume size and the unit is GiB).

In `@docs/03-github-orchestrator/07-advanced-topics/04-garbage-collection.mdx`:
- Around line 42-44: Update the documented CLI example that still uses the
pre-extraction entrypoint "yarn run cli -m garbage-collect --providerStrategy
aws" to the standalone package invocation by replacing it with "npx
`@game-ci/orchestrator` -m garbage-collect --providerStrategy aws" so readers use
the LTS 2.0.0 correct command; locate the code block containing the quoted CLI
example and swap the command string accordingly.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx`:
- Around line 241-251: The current RUNNERS count uses gh api with jq to count
runners with .status == "online"; change the jq filter to count only idle
runners (e.g., .status == "online" and .busy == false) so RUNNERS reflects
available idle self-hosted runners; update the RUNNERS assignment (the gh api
... --jq '[.runners[] | select(.status == "online")] | length' code that sets
RUNNERS) to use the idle filter and leave the subsequent provider logic (echoing
to GITHUB_OUTPUT) unchanged.

In `@docs/03-github-orchestrator/07-advanced-topics/15-massive-projects.mdx`:
- Around line 113-123: The docs conflict on the separator for the LFS paths
input: reconcile and align the example and text to match the canonical LFS agent
definition (LFS_STORAGE_PATHS) by using the same separator and wording; update
the example that shows lfsStoragePaths to use the documented separator (e.g.,
semicolon if LFS_STORAGE_PATHS is semicolon-separated) and adjust the
explanatory sentence to state the exact separator expected, and make the same
change for the duplicate example referenced (the block around lines 230-240) so
both pages consistently document the same syntax for lfsStoragePaths /
LFS_STORAGE_PATHS.

In `@docs/03-github-orchestrator/08-cli/01-getting-started.mdx`:
- Around line 77-98: The docs show a `game-ci build` flow that assumes
Docker-based local execution, but the CLI defaults provider-strategy to "local"
and the build handler (in build.ts) immediately rejects "local" and instructs
users to use "aws" or "k8s"; update the getting-started text to reflect actual
CLI behavior by either (A) changing the example command to include
--provider-strategy aws or --provider-strategy k8s and keep the
Docker/pull/mount bullets, or (B) explicitly note that the default
provider-strategy is local and that local builds are not supported (and show the
error guidance to use aws/k8s), and adjust the bullet list to describe the
aws/k8s execution path instead of auto-pulling a Unity Docker image. Ensure
references to the CLI flag name provider-strategy and the build command (game-ci
build) are present so readers see the required change.
- Around line 18-22: The documented install script URL
"https://raw.githubusercontent.com/game-ci/orchestrator/main/install.sh" returns
404; update the Linux/macOS install instruction in
docs/03-github-orchestrator/08-cli/01-getting-started.mdx to point to the
correct raw install script (or remove the shell-install recommendation) by
replacing that URL with the valid raw.githubusercontent.com path for the
repository's current install script (or a releases-based install URL), and
ensure the one-line curl|sh command and its surrounding text reflect the correct
location and recommendation (verify the new URL serves an executable
install.sh).

In `@docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx`:
- Around line 27-32: The table entry for the Local System provider uses the
value `local-system` but other docs use `local`; change the table row value to
`local` so the CLI flag example matches the canonical provider string used
elsewhere (update the Local System row in the table where `Local System |
`local-system`` appears to `Local System | `local`` to standardize the
`--provider-strategy` value).

---

Minor comments:
In `@docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx`:
- Around line 9-12: The current paragraph starting "Game CI provides Docker
images and GitHub Actions for running Unity workflows..." and the following
"**Best for:** Small to medium projects..." assumes GitHub-hosted runner limits;
either scope this entire section to GitHub-hosted runners by adding an explicit
qualifier like "(for GitHub-hosted runners)" to the section heading and the
opening sentence, or remove GitHub-specific numbers and wording and replace them
with generic phrasing such as "typical CI platform limits" or "CI platform
runner limits" (e.g., change "~14 GB disk" and fixed resource references to
"your CI platform's disk and resource limits"); apply the same change to the
later block that the reviewer called out (the text around lines 24-35) so all
comparisons are consistently scoped or generalized.

In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx`:
- Around line 155-159: Replace the GNU-specific use of "base64 -w 0" in the
kubeconfig encoding instruction with a portable approach: run base64 without the
-w flag and pipe its output through tr to delete newlines so the result is a
single-line, platform-independent base64 string; update the example text in the
docs/03-github-orchestrator/03-examples/02-github-actions.mdx snippet
accordingly so macOS/BSD and Linux users get the same behavior.

In `@docs/03-github-orchestrator/03-examples/04-kubernetes.mdx`:
- Around line 163-171: The docs currently instruct using the GNU-specific
command `base64 -w 0` to encode the kubeconfig for the `KUBE_CONFIG` secret;
update the text to provide a cross-platform alternative by showing both the
Linux (GNU coreutils) form `base64 -w 0` and the macOS form `base64` (or `base64
-b 0` for older macOS), or add a short note explaining that macOS users should
omit `-w 0`, and ensure the example mentions storing the output as the GitHub
Actions secret named `KUBE_CONFIG`.
- Around line 99-109: Update the "CPU and Memory" section and its table to state
that the shown units are an Orchestrator convention that are normalized and
translated into Kubernetes-native units (e.g., CPU -> millicores like 1000m = 1
CPU, memory -> Mi/Gi) rather than implying Kubernetes itself uses "1024 = 1
vCPU" or MB; explicitly mention "Orchestrator normalizes these values to
Kubernetes millicores and Mi/Gi" so readers understand the translation performed
by Orchestrator.

In `@docs/03-github-orchestrator/04-jobs.mdx`:
- Line 136: The link anchor text "elastic-git-storage" in
docs/03-github-orchestrator/04-jobs.mdx doesn't match the target page
"advanced-topics/lfs-agents"; update the link so the display text reads "LFS
agents" to match the target, or change the href to point to a specific section
anchor on advanced-topics/lfs-agents (e.g., add `#elastic-git-storage` if that
section exists) so the link text and destination align.

In `@docs/03-github-orchestrator/05-api-reference.mdx`:
- Around line 34-41: The API reference table for the providerStrategy parameter
is missing several built-in provider names; update the
docs/03-github-orchestrator/05-api-reference.mdx table entry for
`providerStrategy` to list all built-in providers (at minimum: aws, k8s,
local-docker, local, gcp-cloud-run, azure-aci, remote-powershell,
github-actions, gitlab-ci, ansible) so it matches the implementations referenced
by setupSelectedBuildPlatform() and the orchestrator model; ensure the table
cell for `providerStrategy` mentions custom provider formats (GitHub URL, NPM
package, local path) exactly as currently worded and keep the rest of the
parameter rows unchanged.

In `@docs/03-github-orchestrator/05-providers/01-overview.mdx`:
- Around line 22-34: The overview currently presents an authoritative list of
providerStrategy values but omits `gcp-cloud-run`, `azure-aci`, and `gitlab-ci`;
either add rows for these providerStrategy values to the provider table
(`providerStrategy` values: `gcp-cloud-run`, `azure-aci`, `gitlab-ci`) with
short descriptions, or explicitly mark the table as a partial subset and add a
sentence linking to the full provider index (or listing the missing providers)
so readers won’t miss supported strategies.

In `@docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx`:
- Line 161: The docs disagree about the expected format for gitlabProjectId:
update the examples and the reference row for gitlabProjectId so they match
(choose either raw path like my-group/unity-builds or URL-encoded
my-group%2Funity-builds) and clearly state which format consumers must pass;
ensure every occurrence of gitlabProjectId in the GitLab CI dispatch docs
(examples, parameter table, and any sample payloads) is changed to the chosen
format and add a short note showing the alternative encoding if useful for URLs.
- Around line 57-66: The docs use an unpinned action reference "uses:
game-ci/unity-builder@main" which should be replaced with a versioned ref to
ensure reproducibility; update every occurrence (including the instance at lines
~129-137) to a specific tag or release pin (e.g., a semver tag or commit SHA) so
examples in the GitLab CI dispatch snippet and the other workflow block no
longer reference `@main` but a stable version.

In `@docs/03-github-orchestrator/07-advanced-topics/03-custom-job.mdx`:
- Around line 18-19: The phrase "cloud infrastructure" and the admonition to
"Avoid calling this cloud-only infrastructure" incorrectly narrows the scope of
the documented feature; update the text around the customJob description to
refer to "Orchestrator-managed infrastructure" or "supported providers" (and
remove "cloud-only") so it accurately reflects that customJob can run on
multiple provider types (including Local Docker); ensure the sentence mentioning
customJob explicitly uses the symbol name customJob and replaces "cloud
infrastructure" with one of the suggested alternatives.

In `@docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx`:
- Around line 244-264: The CLI Modes table currently reads like the public
game-ci CLI surface; clarify it documents internal decorator-registered modes
(the `@CliFunction` registry) rather than user-facing yargs commands. Update the
paragraph heading and/or a short explanatory sentence above the table to state
these are internal mode names used by the CliFunction registry (see
cli-functions-repository.ts) and not the public commands exposed by the game-ci
entrypoint (which defines yargs commands like build, activate, orchestrate,
status, version, update in src/cli.ts). Keep the existing mode list but add that
distinction so readers know where to look for public CLI usage versus internal
mode handlers.

In `@docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx`:
- Line 196: The related-link entry currently reads "[Cloud
Providers](/docs/github-orchestrator/providers/gcp-cloud-run) — GCP Cloud Run
and Azure ACI" but only links to GCP; update this so GCP and Azure are separate
links: keep the GCP link text/URL ([Cloud Providers] or [GCP Cloud Run]
referencing /docs/github-orchestrator/providers/gcp-cloud-run) and add a second
link for Azure (e.g., [Azure ACI] pointing to the Azure provider doc like
/docs/github-orchestrator/providers/azure-aci or the correct Azure doc slug);
ensure the visible text lists both providers and each has its own accurate href
so Azure docs are discoverable.

In `@docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx`:
- Around line 58-68: Add a new row for the run field `builtClientPath` in the
Run Fields table: explain that `builtClientPath` is the filesystem path to the
built Unity client used when `builtClient: true`, note whether it should be
absolute or relative (e.g., relative to the repository root or workflow working
directory), and mention any default/required format and examples; update the
same table instance referenced later (the second occurrence at the other
location) so both places define `builtClientPath` consistently.

In
`@docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx`:
- Around line 19-24: The table and example conflict over whether storage URIs
like storage://... belong to direct-input or storage-pull; decide which strategy
should accept storage URIs and make the docs consistent by either (A) stating in
the Strategy table that `direct-input` accepts inline content and storage URIs
(update the `direct-input` row) and adding a clarifying sentence where
`syncStrategy: direct-input` is shown (including the `storage://...` example),
or (B) changing the example that currently shows `syncStrategy: direct-input`
with a `storage://...` URI to use `syncStrategy: storage-pull` and ensure
surrounding text explains that `storage-pull` is for remote storage URIs; update
all occurrences cited (around lines 19-24, 47-52, 124-127) to match the chosen
behavior.

---

Nitpick comments:
In `@docs/03-github-orchestrator/03-examples/03-aws.mdx`:
- Around line 151-166: Add a short note under the "S3 Upload + Steam Deploy"
example explaining that STEAM_PASSWORD (and STEAM_USERNAME/STEAM_APPID) may
require special handling for Steam Guard/2FA: instruct users to store
credentials in GitHub Secrets, mention TOTP/Steam Guard and pre-authenticated
sentry files as possible solutions, warn that environment variables expose the
password to the container, and optionally link to Steam/SteamCMD authentication
docs and the repo's steam-deploy-client containerHookFiles guidance so users
know where to configure sentry or token-based auth.

In `@docs/03-github-orchestrator/04-jobs.mdx`:
- Around line 185-189: The "Hooks" link in the Next Steps list currently points
to advanced-topics/hooks/container-hooks but the docs mention both container
hooks and command hooks; update the link to either point to a hooks
overview/index (advanced-topics/hooks or equivalent) if that page exists, or
change the link text from "Hooks" to "Container Hooks" to accurately reflect the
target (modify the list item containing the link in the Next Steps block and the
anchor text accordingly).

In `@docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx`:
- Around line 74-83: Replace the floating main ref on the GitHub Action usage
with a stable version tag: locate the uses: game-ci/unity-builder@main entry in
the GitHub Actions example and change it to a versioned tag (e.g., `@v4` or the
appropriate released tag) to match other provider examples and ensure
consistency and stability; update any accompanying text if it implies tracking
main.
- Around line 137-146: The GitHub Actions step is pinned to the branch tag
"game-ci/unity-builder@main"; update that to the versioned tag
"game-ci/unity-builder@v4" for consistency with other docs. Locate the action
usage line (the "uses: game-ci/unity-builder@main" entry) in the GitHub Actions
example and change the tag to "@v4", keeping the rest of the step fields
(providerStrategy, targetPlatform, gitPrivateToken, githubActionsRepo,
githubActionsWorkflow, githubActionsToken, githubActionsRef) unchanged.

In `@docs/03-github-orchestrator/05-providers/04-local-docker.mdx`:
- Line 1: Add missing top-matter to the document so it appears correctly in the
docs sidebar: insert a YAML frontmatter block at the very top of the "Local
Docker" doc containing at least the title and a sidebar_position field (e.g.,
title: "Local Docker" and sidebar_position: <number>) to match other provider
docs; place the block before the existing "# Local Docker" header and choose a
numeric sidebar_position consistent with sibling files to ensure correct
ordering in the sidebar.
- Around line 23-28: Update the example CLI invocation so it matches the
published CLI docs: replace the development command "yarn run cli -m cli-build"
with the official "game-ci build" form (keeping the flags --providerStrategy,
--projectPath, --targetPlatform intact) or, if you intend to show a dev-only
invocation, add a short note clarifying that "yarn run cli -m cli-build" is for
local development while "game-ci build" is the published command; adjust the
example around the existing flags (--providerStrategy local-docker,
--projectPath, --targetPlatform StandaloneLinux64) accordingly.

In `@docs/03-github-orchestrator/05-providers/06-custom-providers.mdx`:
- Around line 106-113: The garbageCollect method signature uses the boxed type
Number; update the parameter type to the TypeScript primitive by changing
olderThan: Number to olderThan: number in the garbageCollect declaration to
match TS conventions (modify the signature in the garbageCollect method
definition/interface).

In `@docs/03-github-orchestrator/05-providers/07-ansible.mdx`:
- Around line 49-58: Update the GitHub Action reference in the Ansible example
to use the versioned tag used elsewhere (change the uses value from
game-ci/unity-builder@main to game-ci/unity-builder@v4) so it matches Kubernetes
and AWS examples; verify the ansible example block (the uses line and
surrounding snippet: providerStrategy/ansible, ansibleInventory,
ansiblePlaybook, ansibleExtraVars, ansibleVaultPassword) still works with `@v4`
and adjust any option names if necessary to keep examples consistent across
provider docs.

In `@docs/03-github-orchestrator/07-advanced-topics/04-garbage-collection.mdx`:
- Around line 32-38: Add a short clarifying sentence after the example YAML that
explains why the action still references game-ci/unity-builder: state that this
workflow path uses game-ci/unity-builder which automatically loads
`@game-ci/orchestrator` via the plugin interface (so the example isn’t showing
Orchestrator bundled inside unity-builder), and mention you can instead call
`@game-ci/orchestrator` directly if using the standalone package; reference the
YAML keys shown (uses: game-ci/unity-builder@v4 and mode: garbage-collect) to
indicate where this behavior applies.

In `@docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx`:
- Around line 101-109: Add a short clarifying sentence to each YAML example in
the Post-Processing Pipelines section (the blocks showing outputPipelines,
customOutputTypes, etc.) that explicitly states how the YAML should be provided:
either passed as a multiline YAML string to the action input (e.g., "pass as a
multiline YAML string to the outputPipelines input") or saved to the repo at
.game-ci/output-types.yml (e.g., "or store this configuration in
.game-ci/output-types.yml and reference it from the action"). Update the
examples at the affected locations (the blocks containing outputPipelines,
customOutputTypes and similar nested YAML snippets) to include this short note
so readers know whether to use the with: input or a repository file.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`:
- Around line 46-56: Reword the "Automatic Recovery" paragraph to state that
gitAutoRecover defaults to 'true' unconditionally but only has effect when
gitIntegrityCheck is enabled; specifically, update the sentence currently
reading "the default when `gitIntegrityCheck` is on" to something like
"gitAutoRecover defaults to 'true', but it only performs recovery actions when
`gitIntegrityCheck` is enabled" and ensure the subsequent steps still describe
the recovery sequence (remove corrupted `.git`, `git init`, checkout on next
step) and that the behavior is conditional on `gitIntegrityCheck` being active.
- Around line 156-165: Update the example archive timestamps in the snippet
under /mnt/build-archives/ (the entries for StandaloneLinux64 and
StandaloneWindows64) from 2025 to 2026 so the example shows current-year dates
(e.g., change build-2025-01-15T10-30-00-000Z to build-2026-01-15T10-30-00-000Z
and the other 2025 dates similarly).

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Fix the secrets cross-reference and stop pointing new users at the legacy flow.

The ../secrets#-pulling-secrets-from-external-sources anchor does not exist in docs/03-github-orchestrator/06-secrets.mdx, and the sample underneath still uses inputPullCommand even though that page recommends secretSource. This will fail the internal-link check and route readers to deprecated usage.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/01-command-line.mdx` around lines 55
- 66, Update the cross-reference and example to point to the current secrets
docs and modern API: replace the broken anchor link
../secrets#-pulling-secrets-from-external-sources with the correct anchor in
docs/03-github-orchestrator/06-secrets.mdx (use the actual section anchor for
"Pull Secrets" or the top-level secrets page if no anchor exists) and change the
example flag from --inputPullCommand to the recommended --secretSource usage
(and corresponding variable names UNITY_EMAIL, UNITY_SERIAL, UNITY_PASSWORD) so
the sample matches the secrets page and avoids deprecated flow references.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

find . -name "02-github-actions.mdx" -type f

Repository: game-ci/documentation

Length of output: 208

---

🏁 Script executed:

cat -n docs/03-github-orchestrator/03-examples/02-github-actions.mdx | head -250

Repository: game-ci/documentation

Length of output: 8299

---

🏁 Script executed:

# Check if there's any mention of OIDC or role-to-assume in the documentation
rg -i "oidc|role-to-assume" docs/03-github-orchestrator/

Repository: game-ci/documentation

Length of output: 47

---

🏁 Script executed:

# Check aws-actions/configure-aws-credentials action version and capabilities
web_search aws-actions configure-aws-credentials GitHub OIDC role-to-assume v4

Repository: game-ci/documentation

Length of output: 115

---

🌐 Web query:

aws-actions/configure-aws-credentials v4 GitHub OIDC role-to-assume support

💡 Result:

Yes—aws-actions/configure-aws-credentials@v4 supports GitHub Actions OIDC and uses the role-to-assume input to assume an IAM role via STS AssumeRoleWithWebIdentity (i.e., no long-lived AWS keys required). You must grant the workflow permissions: id-token: write so the action can request a GitHub OIDC JWT, then exchange it for AWS credentials while assuming the specified role. By default the OIDC audience is sts.amazonaws.com (configurable via the audience input if needed). [1][2]

Example:

permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v4
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      aws-region: us-east-1
      role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
      role-session-name: GitHubActions

Sources: [1] [2]

---

🏁 Script executed:

# Verify base64 -w 0 portability
man base64 2>/dev/null | grep -A 2 "\-w" || echo "base64 -w flag documentation check"
# Also check if there's a portable alternative mentioned
rg "base64" docs/

Repository: game-ci/documentation

Length of output: 4446

---

🏁 Script executed:

# Check if there are any AWS configuration examples or docs in the repo that use OIDC
rg "role-to-assume|id-token" docs/

Repository: game-ci/documentation

Length of output: 47

---

Replace long-lived AWS keys with GitHub OIDC authentication.

The workflows at these locations use AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets. For a canonical example, prefer the OIDC method with role-to-assume, which avoids storing long-lived IAM credentials in GitHub secrets:

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
      aws-region: eu-west-2

This applies to lines 33–38, 76–81, and 228–233.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx` around lines
33 - 38, The workflow uses long-lived secrets AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY with aws-actions/configure-aws-credentials@v4; replace
this pattern by enabling GitHub OIDC: add a top-level permissions block granting
id-token: write and contents: read, and update the configure-aws-credentials
step to use role-to-assume instead of aws-access-key-id/aws-secret-access-key
(keep aws-region as before), referencing the IAM role ARN (role-to-assume) for
the GitHubActionsRole; make the same replacement for other identical occurrences
that use aws-actions/configure-aws-credentials@v4.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Count idle runners here, not just online runners.

Line 246 currently treats any online runner as available, so this example will still route to local-docker when every self-hosted runner is already busy. That breaks the fallback behavior this section is demonstrating.

Suggested fix

-          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online")] | length')
+          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online" and .busy == false)] | length')

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- name: Check if self-hosted runner is available
	id: pick
	env:
	GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	run: |
	RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online")] | length')
	if [[ "$RUNNERS" -gt 0 ]]; then
	echo "provider=local-docker" >> "$GITHUB_OUTPUT"
	else
	echo "provider=aws" >> "$GITHUB_OUTPUT"
	fi
	- name: Check if self-hosted runner is available
	id: pick
	env:
	GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	run: |
	RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online" and .busy == false)] | length')
	if [[ "$RUNNERS" -gt 0 ]]; then
	echo "provider=local-docker" >> "$GITHUB_OUTPUT"
	else
	echo "provider=aws" >> "$GITHUB_OUTPUT"
	fi

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx` around
lines 241 - 251, The current RUNNERS count uses gh api with jq to count runners
with .status == "online"; change the jq filter to count only idle runners (e.g.,
.status == "online" and .busy == false) so RUNNERS reflects available idle
self-hosted runners; update the RUNNERS assignment (the gh api ... --jq
'[.runners[] | select(.status == "online")] | length' code that sets RUNNERS) to
use the idle filter and leave the subsequent provider logic (echoing to
GITHUB_OUTPUT) unchanged.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

The first build flow doesn't match current CLI behavior.

game-ci build defaults provider-strategy to local, and the handler immediately throws for local builds, telling users to use aws or k8s instead. Because of that, the example as written won't run, and the follow-up bullet list about auto-pulling a Unity Docker image/mounting the project describes a different execution path than the standalone CLI currently implements. (raw.githubusercontent.com)

Suggested doc adjustment

 game-ci build \
+  --provider-strategy aws \
   --target-platform StandaloneLinux64

-The CLI will:
-
-1. Pull the matching Unity Docker image
-2. Mount your project into a container
-3. Run the Unity build
-4. Output build artifacts to the `build/` directory
+The CLI will:
+
+1. Resolve your project settings locally
+2. Dispatch the build through the selected orchestrator provider
+3. Stream status back to the terminal
+4. Write artifacts when the remote workflow completes

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/08-cli/01-getting-started.mdx` around lines 77 -
98, The docs show a `game-ci build` flow that assumes Docker-based local
execution, but the CLI defaults provider-strategy to "local" and the build
handler (in build.ts) immediately rejects "local" and instructs users to use
"aws" or "k8s"; update the getting-started text to reflect actual CLI behavior
by either (A) changing the example command to include --provider-strategy aws or
--provider-strategy k8s and keep the Docker/pull/mount bullets, or (B)
explicitly note that the default provider-strategy is local and that local
builds are not supported (and show the error guidance to use aws/k8s), and
adjust the bullet list to describe the aws/k8s execution path instead of
auto-pulling a Unity Docker image. Ensure references to the CLI flag name
provider-strategy and the build command (game-ci build) are present so readers
see the required change.

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx (1)

105-115: ⚠️ Potential issue | 🟠 Major

Document the enforced timeout limits.

Line 108 and Line 113 still describe run-task and watch-workflow as unbounded, but provider authors need the real limits here or they will implement the wrong heartbeat/cancellation behavior.

Suggested doc fix

 | Subcommand           | Purpose                                | Timeout   |
 | -------------------- | -------------------------------------- | --------- |
 | `setup-workflow`     | Initialize infrastructure              | 300s      |
-| `run-task`           | Execute the build                      | No limit  |
+| `run-task`           | Execute the build                      | 2h        |
 | `cleanup-workflow`   | Tear down infrastructure               | 300s      |
 | `garbage-collect`    | Remove old resources                   | 300s      |
 | `list-resources`     | List active resources                  | 300s      |
 | `list-workflow`      | List active workflows                  | 300s      |
-| `watch-workflow`     | Watch a workflow until completion      | No limit  |
+| `watch-workflow`     | Watch a workflow until completion      | 1h        |
 
-`run-task` and `watch-workflow` have no timeout because builds can run for hours.
+`run-task` is limited to 2 hours and `watch-workflow` to 1 hour.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 105 - 115, The docs claim `run-task` and `watch-workflow` have "No limit"
but the system enforces timeouts; update the table entries for the `run-task`
and `watch-workflow` subcommands to show the actual enforced timeout values
(replace "No limit" with the real durations), and adjust the trailing
explanatory sentence to state those concrete limits. Locate where those timeouts
are defined in the code/config (search for the `run-task` and `watch-workflow`
timeout constants or enforcement logic) and use those exact values in the table
and sentence so provider authors can implement correct heartbeat/cancellation
behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx`:
- Around line 157-159: The default/unknown-command handler (the case '*' branch
that currently echoes '{"success": false, "error": "Unknown command: ..."}' to
stderr) must write the JSON error payload to stdout instead of stderr; change
the echo redirection so the structured JSON goes to stdout and keep the exit 1
to signal failure (preserve the same message formatting but remove the >&2
redirection) so the orchestrator can parse the response while stderr remains
available for logs.
- Around line 128-135: The run-task branch always prints {"success": true}
regardless of docker run result; modify the run-task handler (the shell snippet
using docker run) to capture docker run's exit code (e.g., run the docker run
line, save $? into a variable), then conditionally emit JSON with success: true
when exit code is 0 and success: false (including the exit code and/or error
output) when non-zero, and exit the script with the same exit code; update the
block that currently contains "docker run ... 2>&1" and the following echo to
perform this check and conditional JSON output.

---

Duplicate comments:
In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx`:
- Around line 105-115: The docs claim `run-task` and `watch-workflow` have "No
limit" but the system enforces timeouts; update the table entries for the
`run-task` and `watch-workflow` subcommands to show the actual enforced timeout
values (replace "No limit" with the real durations), and adjust the trailing
explanatory sentence to state those concrete limits. Locate where those timeouts
are defined in the code/config (search for the `run-task` and `watch-workflow`
timeout constants or enforcement logic) and use those exact values in the table
and sentence so provider authors can implement correct heartbeat/cancellation
behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c6feafb0-15c5-4375-92ac-dd2e37e5a54f

📥 Commits

Reviewing files that changed from the base of the PR and between 776342d and a113d55.

📒 Files selected for processing (5)

• docs/03-github-orchestrator/04-jobs.mdx
• docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx
• docs/03-github-orchestrator/08-cli/01-getting-started.mdx
• docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx

✅ Files skipped from review due to trivial changes (3)

• docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx
• docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx
• docs/03-github-orchestrator/04-jobs.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/03-github-orchestrator/08-cli/01-getting-started.mdx

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

head -135 "docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx" | tail -20

Repository: game-ci/documentation

Length of output: 568

---

The run-task example reports failed builds as success.

If docker run exits non-zero, this snippet still prints {"success": true}. Copy-pasted providers would silently mark broken builds as successful. The exit code must be checked before reporting the result.

Suggested fix

   run-task)
     read request
     image=$(echo "$request" | jq -r '.params.image')
     commands=$(echo "$request" | jq -r '.params.commands')
     # Stream build output, then send JSON result
-    docker run --rm "$image" /bin/sh -c "$commands" 2>&1
-    echo '{"success": true, "result": "done"}'
+    if docker run --rm "$image" /bin/sh -c "$commands" 2>&1; then
+      echo '{"success": true, "result": "done"}'
+    else
+      echo '{"success": false, "error": "Container exited with a non-zero status"}'
+      exit 1
+    fi
     ;;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	run-task)
	read request
	image=$(echo "$request" | jq -r '.params.image')
	commands=$(echo "$request" | jq -r '.params.commands')
	# Stream build output, then send JSON result
	docker run --rm "$image" /bin/sh -c "$commands" 2>&1
	echo '{"success": true, "result": "done"}'
	;;
	run-task)
	read request
	image=$(echo "$request" | jq -r '.params.image')
	commands=$(echo "$request" | jq -r '.params.commands')
	# Stream build output, then send JSON result
	if docker run --rm "$image" /bin/sh -c "$commands" 2>&1; then
	echo '{"success": true, "result": "done"}'
	else
	echo '{"success": false, "error": "Container exited with a non-zero status"}'
	exit 1
	fi
	;;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 128 - 135, The run-task branch always prints {"success": true} regardless
of docker run result; modify the run-task handler (the shell snippet using
docker run) to capture docker run's exit code (e.g., run the docker run line,
save $? into a variable), then conditionally emit JSON with success: true when
exit code is 0 and success: false (including the exit code and/or error output)
when non-zero, and exit the script with the same exit code; update the block
that currently contains "docker run ... 2>&1" and the following echo to perform
this check and conditional JSON output.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, let's locate and examine the file
find . -name "12-cli-provider-protocol.mdx" -type f

Repository: game-ci/documentation

Length of output: 136

---

🏁 Script executed:

# Get the file and examine the context around lines 157-159
cat -n docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx | sed -n '130,180p'

Repository: game-ci/documentation

Length of output: 1980

---

🏁 Script executed:

# Also search for protocol documentation about stdout/stderr handling
rg -i "protocol|stdout|stderr" docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx | head -30

Repository: game-ci/documentation

Length of output: 768

---

Send the terminal error payload to stdout.

According to the CLI Provider Protocol, all final JSON responses—including error responses—must be written to stdout. The protocol specifies that stderr is forwarded only to logs, not parsed for structured responses. The current implementation redirects the error JSON to stderr, which prevents the orchestrator from receiving the structured error response. All other command handlers in this file correctly send JSON responses to stdout.

Suggested fix

   *)
-    echo '{"success": false, "error": "Unknown command: '"$1"'"}' >&2
+    echo '{"success": false, "error": "Unknown command: '"$1"'"}'
     exit 1

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	*)
	echo '{"success": false, "error": "Unknown command: '"$1"'"}' >&2
	exit 1
	*)
	echo '{"success": false, "error": "Unknown command: '"$1"'"}'
	exit 1

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 157 - 159, The default/unknown-command handler (the case '*' branch that
currently echoes '{"success": false, "error": "Unknown command: ..."}' to
stderr) must write the JSON error payload to stdout instead of stderr; change
the echo redirection so the structured JSON goes to stdout and keep the exit 1
to signal failure (preserve the same message formatting but remove the >&2
redirection) so the orchestrator can parse the response while stderr remains
available for logs.

[coderabbitai]

Actionable comments posted: 13

♻️ Duplicate comments (8)

docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx (1)

241-251: ⚠️ Potential issue | 🟠 Major

Count idle runners, not just online runners.

Line 246 counts any online runner as available, so this example will route to local-docker even when all self-hosted runners are busy, breaking the fallback behavior.

Note that other examples in this same file (lines 315-316 and 441-442) correctly filter for idle runners using .busy == false. This inconsistency should be resolved by applying the same pattern here.

🔧 Proposed fix to match the correct pattern used elsewhere in this file

-          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online")] | length')
+          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online" and .busy == false)] | length')

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx` around
lines 241 - 251, The RUNNERS count logic uses the gh api call assigned to the
RUNNERS variable and incorrectly counts any online runners; update the jq filter
in the RUNNERS assignment (the gh api repos/${{ github.repository
}}/actions/runners --jq '...') to select idle runners by using select(.status ==
"online" and .busy == false) or the equivalent pattern used elsewhere
(select(.busy == false)) so the script only treats truly idle self-hosted
runners as available before writing provider=local-docker to GITHUB_OUTPUT.

docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx (3)

105-115: ⚠️ Potential issue | 🟠 Major

Update the timeout table to match the implementation.

This still documents run-task and watch-workflow as unlimited. Provider authors will design the wrong heartbeat and retry behavior if the reference promises “No limit” for long-running commands.

Suggested change

 | `setup-workflow`   | Initialize infrastructure         | 300s     |
-| `run-task`         | Execute the build                 | No limit |
+| `run-task`         | Execute the build                 | 2h       |
 | `cleanup-workflow` | Tear down infrastructure          | 300s     |
 | `garbage-collect`  | Remove old resources              | 300s     |
 | `list-resources`   | List active resources             | 300s     |
 | `list-workflow`    | List active workflows             | 300s     |
-| `watch-workflow`   | Watch a workflow until completion | No limit |
+| `watch-workflow`   | Watch a workflow until completion | 1h       |
 
-`run-task` and `watch-workflow` have no timeout because builds can run for hours.
+`run-task` is limited to 2 hours and `watch-workflow` to 1 hour.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 105 - 115, The timeout table incorrectly documents `run-task` and
`watch-workflow` as "No limit"; update the table so the Timeout column matches
the implementation (replace "No limit" for `run-task` and `watch-workflow` with
the actual timeout values used by the codebase), and ensure the entries for
`run-task`, `watch-workflow`, and any related subcommands like `setup-workflow`,
`cleanup-workflow`, `garbage-collect`, `list-resources`, and `list-workflow`
precisely reflect the implementation to avoid misleading provider authors about
heartbeat/retry behavior.

---

128-135: ⚠️ Potential issue | 🟠 Major

Propagate docker run failures in the result JSON.

The run-task branch always emits success: true, so a failed container still looks like a successful build to anyone copying this example.

Suggested change

   run-task)
     read request
     image=$(echo "$request" | jq -r '.params.image')
     commands=$(echo "$request" | jq -r '.params.commands')
     # Stream build output, then send JSON result
-    docker run --rm "$image" /bin/sh -c "$commands" 2>&1
-    echo '{"success": true, "result": "done"}'
+    if docker run --rm "$image" /bin/sh -c "$commands" 2>&1; then
+      echo '{"success": true, "result": "done"}'
+    else
+      echo '{"success": false, "error": "Container exited with a non-zero status"}'
+      exit 1
+    fi
     ;;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 128 - 135, In the run-task branch, the script always echoes '{"success":
true ...}' regardless of the docker run outcome; modify the block in the
run-task handler to capture the docker run exit code and output (e.g., run the
docker run and save its stdout/stderr and $? into variables), then emit a JSON
result where "success" is true only when the exit code is zero and include the
exit code and output in the JSON result; update the code around the docker run
invocation and the final echo that currently emits '{"success": true, "result":
"done"}' so it conditionally reflects the actual docker run result.

---

157-159: ⚠️ Potential issue | 🟠 Major

Write the structured error response to stdout.

The protocol says stdout carries the final JSON response; sending the unknown-command payload to stderr makes it unavailable to the orchestrator parser.

Suggested change

   *)
-    echo '{"success": false, "error": "Unknown command: '"$1"'"}' >&2
+    echo '{"success": false, "error": "Unknown command: '"$1"'"}'
     exit 1

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 157 - 159, The catch-all case (*) currently writes the unknown-command
JSON to stderr using the echo ... >&2 redirection, but the protocol requires the
final JSON be emitted on stdout; change the fallback in the "*" case so the JSON
error is echoed to stdout (remove the stderr redirection) and then exit 1,
ensuring the orchestrator receives the structured response on stdout.

docs/03-github-orchestrator/03-examples/02-github-actions.mdx (2)

135-146: ⚠️ Potential issue | 🟠 Major

Either remove aws-s3-upload-build here or document AWS auth for it.

This Kubernetes example enables the S3 upload hook but never shows any AWS credential setup, so the copied workflow is incomplete.

Suggested change

       - uses: game-ci/unity-builder@v4
         id: build
         with:
           providerStrategy: k8s
           targetPlatform: ${{ matrix.targetPlatform }}
           gitPrivateToken: ${{ secrets.GITHUB_TOKEN }}
           unityVersion: 2022.3.0f1
           kubeVolumeSize: 10Gi
           containerCpu: 1024
           containerMemory: 4096
-          containerHookFiles: aws-s3-upload-build
           githubCheck: true

If S3 upload is intentional here, add the AWS auth step explicitly instead of removing the hook.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx` around lines
135 - 146, The workflow enables the S3 upload hook via containerHookFiles:
aws-s3-upload-build but provides no AWS credentials; either remove the
aws-s3-upload-build entry or add an explicit AWS authentication step before the
build step (e.g., configure AWS credentials/role using an actions/aws or custom
step) so the aws-s3-upload-build hook can access S3; update the docs to show the
added AWS auth step and reference containerHookFiles and aws-s3-upload-build so
readers know where the credentials are required.

---

33-38: ⚠️ Potential issue | 🟠 Major

Prefer GitHub OIDC in the canonical AWS workflows.

These examples still normalize long-lived AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY secrets. The official action recommends OIDC with role-to-assume, which avoids storing static AWS keys in repository secrets and is the safer baseline for GitHub Actions docs. (github.com)

Suggested change

+permissions:
+  id-token: write
+  contents: read
+
 jobs:
   build:
@@
       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v4
         with:
-          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          role-to-assume: arn:aws:iam::<account-id>:role/<github-actions-role>
           aws-region: eu-west-2

The required-secrets table should then describe the IAM role/OIDC setup instead of static key material.

Also applies to: 76-81, 98-104, 228-233, 275-280

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx` around lines
33 - 38, Replace the long‑lived AWS secret usage in the "Configure AWS
Credentials" step that uses aws-actions/configure-aws-credentials@v4 and the
keys aws-access-key-id/aws-secret-access-key with the recommended GitHub OIDC
settings: remove the static secret inputs and add role-to-assume (ARN of the IAM
role), role-session-name (optional), and aws-region; update the required-secrets
table/output docs to describe the IAM role and GitHub OIDC trust configuration
(instead of static key material). Also apply the same change to the other
occurrences of the "Configure AWS Credentials" step in this document so all
examples use OIDC/role-to-assume.

docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx (1)

68-70: ⚠️ Potential issue | 🟠 Major

Make the documented default valid for in-memory.

gcpDiskSizeGb is documented as the in-memory volume size with a max of 32, but the default shown here is 100. A reader copying the defaults starts from an impossible value.

Suggested change

-| `gcpDiskSizeGb`     | `100`                   | In-memory volume size (for `in-memory`, max 32) |
+| `gcpDiskSizeGb`     | `32`                    | In-memory volume size (for `in-memory`, max 32) |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx` around lines
68 - 70, The table's default for gcpDiskSizeGb is invalid for in-memory
(currently `100` while max is 32); update the default value shown for
`gcpDiskSizeGb` to a valid in-memory size (e.g., `32`) in the
docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx table so the
documented default is achievable when using `in-memory` volumes and ensure the
cell still describes it as the in-memory volume size with max 32.

docs/03-github-orchestrator/08-cli/01-getting-started.mdx (1)

80-101: ⚠️ Potential issue | 🟠 Major

Re-verify the “first build” flow against current CLI behavior.

This section still assumes game-ci build performs a local Docker/native build, but the standalone CLI behavior previously flagged in this PR rejected provider-strategy=local. If that implementation is still current, this onboarding flow is materially wrong and should either show --provider-strategy aws|k8s or explain that local builds are not supported yet.

Suggested change

 game-ci build \
+  --provider-strategy aws \
   --target-platform StandaloneLinux64

-The CLI will:
-
-1. Pull the matching Unity Docker image
-2. Mount your project into a container
-3. Run the Unity build
-4. Output build artifacts to the `build/` directory
+The CLI will:
+
+1. Resolve your local project settings
+2. Dispatch the build through the selected orchestrator provider
+3. Stream workflow status back to the terminal
+4. Write artifacts when the remote workflow completes

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/08-cli/01-getting-started.mdx` around lines 80 -
101, Re-check current CLI behavior for "game-ci build" and update this
onboarding section to reflect whether local Docker/native builds are supported;
if local/provider-strategy=local is unsupported, change the example and text to
show a supported provider (e.g., add a --provider-strategy aws or
--provider-strategy k8s example) or add a clear note that local builds are not
yet supported; ensure references to auto-detection of Unity version and the
example commands (the `game-ci build` invocation and the
`--unity-version`/`--target-platform` flags) are adjusted accordingly so the
documented "first build" flow matches actual behavior.

🧹 Nitpick comments (1)

docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx (1)

86-107: Workflow description is WinRM-specific but SSH transport is also supported.

The mermaid diagram (step 1: "Test connection (Test-WSMan)") and the explanation at line 99 describe WinRM-only behavior. For SSH transport, Test-WSMan is not applicable. Consider noting that this diagram represents the WinRM flow, or adding a brief note about how SSH connectivity verification differs.

📝 Suggested clarification

 1. **Setup**  -  The orchestrator tests connectivity to the remote host using `Test-WSMan`.
+   (For SSH transport, standard SSH connectivity is verified instead.)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx` around
lines 86 - 107, The diagram and description currently present a WinRM-only flow
(uses Test-WSMan and PS-based credential creation) but claim SSH is supported;
update the text around the mermaid block to clarify that the diagram illustrates
the WinRM flow specifically and add a short note describing SSH differences:
state that Test-WSMan is not used for SSH, Invoke-Command should be called with
-HostName for SSH transport, and that credential handling differs from the
PScredential created from remotePowershellCredential; mention that SSH
connectivity verification (e.g., SSH key or password-based host reachability)
must occur instead of Test-WSMan.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/03-github-orchestrator/01-introduction.mdx`:
- Around line 29-31: The admonition starting with the literal string ":::info
Standalone Package" is malformed because its content and the closing ":::"
are on the same line; fix the Docusaurus admonition by placing the content on
the following line(s) and ensuring the closing ":::"
is on its own line so the block looks like an opening ":::info ..." line, the
content lines, then a standalone ":::". Update the block that begins with
":::info Standalone Package" accordingly.

In `@docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx`:
- Around line 6-7: Replace the inline admonition syntax ":::caution Experimental
This provider is experimental. APIs and behavior may change between releases.
:::" with a proper block admonition: put the label ":::caution" on its own
opening line, place the title "Experimental" on the next line (or as first line
of content), then the explanatory text on following lines, and finally close
with a standalone ":::". Locate the current ":::caution ... :::" occurrence and
ensure the closing delimiter is on its own line and the content is separated
from the label to conform to Docusaurus/MDX block admonition rules.

In `@docs/03-github-orchestrator/05-providers/11-azure-aci.mdx`:
- Around line 7-8: The inline single-line admonition ":::caution Experimental
This provider is experimental. APIs and behavior may change between releases.
:::" is invalid Docusaurus syntax; replace it with a block-level admonition
using opening and closing fences and blank lines: use an opening fence like
":::caution" on its own line, a blank line, the body text "Experimental This
provider is experimental. APIs and behavior may change between releases." on its
own line(s), another blank line, and the closing fence ":::". Ensure there are
empty lines between the fences and the body so Docusaurus will render the
admonition correctly.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx`:
- Around line 121-155: The example handler uses `read request` in each case
branch (setup-workflow, run-task, cleanup-workflow, garbage-collect,
list-resources, list-workflow, watch-workflow) which only reads up to the first
newline and will truncate multiline JSON; replace each `read request` with
`request=$(cat)` so the full stdin payload (potentially pretty-printed JSON) is
captured before using jq or docker run, ensuring jq -r '.params.*' and other
JSON parsing operate on the complete object.

In `@docs/03-github-orchestrator/06-secrets.mdx`:
- Around line 43-53: Update the example under secretSource: aws-secrets-manager
to show short-lived OIDC/assume-role auth as the primary pattern (e.g.,
reference GitHub OIDC/configure-aws-credentials + role-to-assume and
AWS_DEFAULT_REGION) and remove the long-lived
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY as the main copy-paste; instead move
those two variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) into a clearly
labeled fallback note explaining static keys are unsupported by default and
should be avoided. Keep secretSource: aws-secrets-manager and AWS_DEFAULT_REGION
in the example so readers know which fields remain required.
- Around line 204-205: Replace the ambiguous sentence "Secrets are created as
native Kubernetes Secret objects and mounted to job containers as environment
variables." with precise wording that explains both mechanisms: state that
secrets are created as Kubernetes Secret objects and are exposed to job
containers either via environment variable references (envFrom/env) or mounted
as files in a volume, and keep the note that the orchestrator handles creation
and cleanup automatically; update the exact sentence in
docs/03-github-orchestrator/06-secrets.mdx where the current phrasing appears.
- Around line 186-195: Call out that the legacy shortcut names (used with
inputPullCommand, e.g., aws-secret-manager and gcp-secret-manager) are different
from the new secretSource identifiers (e.g., aws-secrets-manager); update the
docs around the YAML example to add a clear note warning that inputPullCommand:
aws-secret-manager is NOT the same as secretSource: aws-secrets-manager and that
copy-pasting between legacy and new configs will fail unless the identifier is
converted, referencing the exact symbols inputPullCommand, aws-secret-manager,
secretSource, and aws-secrets-manager so readers can spot the mismatch quickly.

In `@docs/03-github-orchestrator/07-advanced-topics/01-caching.mdx`:
- Line 66: Typo: add the missing period after "etc" in the table cell string
"Flexible cloud storage via [rclone](https://rclone.org). Supports 70+ backends
(Google Cloud, Azure Blob, Backblaze, SFTP, etc)"—update that string (the row
starting with "Rclone | `rclone` | ...") to end the parenthetical with "etc." so
it reads "(Google Cloud, Azure Blob, Backblaze, SFTP, etc.)."

In `@docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx`:
- Around line 60-68: The Run Fields table is missing the builtClientPath field
used in examples; add a new table row documenting `builtClientPath`
(description: Path to the built client used when `builtClient: true`) alongside
the other fields in the Run Fields table so readers see the example's
`builtClientPath: ./Builds/StandaloneLinux64` is supported; update the table
near the existing `builtClient`/`filters`/`timeout` entries and ensure the field
name is formatted as `builtClientPath` to match the example.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`:
- Around line 51-56: The sentence "The checkout action completes the clone on
the next step" is ambiguous; update the wording to explicitly state that the
orchestrator's internal checkout/sync phase (not a later GitHub Actions workflow
step) will re-populate the repository immediately after re-initialization so
readers using the unity-builder inputs understand no extra post-build checkout
is required—replace the phrase with something like "the orchestrator's internal
checkout/sync phase will re-populate the repository immediately after
re-initialization" and ensure references to "checkout action" are clarified to
mean the orchestrator's own checkout step.
- Around line 7-10: The intro currently states "All features are opt-in via
action inputs" but the "GIT_CONFIG_NOSYSTEM=1" section describes automatic Git
hardening; update the intro paragraph to say that most reliability features are
opt-in via action inputs while explicitly calling out that Git hardening
(referenced by the GIT_CONFIG_NOSYSTEM=1 section) is applied automatically as an
exception, and apply the same clarification to the later paragraph covering
lines 169-174 so the document no longer contradicts itself.
- Around line 135-142: Add a note stating that the archival step may move (not
just copy) the original build output, which can remove the usual build output
path on same-device runners; explicitly tell readers that downstream steps
should read artifacts from the archive location (use the
{archivePath}/{platform}/build-{timestamp} pattern) instead of the original
build output path when archival is enabled, and mention that cross-device moves
fall back to copying so behavior differs by runner.

In `@docs/03-github-orchestrator/08-cli/02-build-command.mdx`:
- Around line 116-126: Update the Provider Strategy table in the build command
docs to include the missing `local-docker` option: modify the description for
`--provider-strategy` (used by the `build` command) to list allowed values as
`local`, `local-docker`, `k8s`, or `aws` and add a short note that
`local-docker` is a built-in strategy, keeping the existing reference to
[Orchestrate Command] for cloud-specific options to ensure parity with the
orchestrate command docs.

---

Duplicate comments:
In `@docs/03-github-orchestrator/03-examples/02-github-actions.mdx`:
- Around line 135-146: The workflow enables the S3 upload hook via
containerHookFiles: aws-s3-upload-build but provides no AWS credentials; either
remove the aws-s3-upload-build entry or add an explicit AWS authentication step
before the build step (e.g., configure AWS credentials/role using an actions/aws
or custom step) so the aws-s3-upload-build hook can access S3; update the docs
to show the added AWS auth step and reference containerHookFiles and
aws-s3-upload-build so readers know where the credentials are required.
- Around line 33-38: Replace the long‑lived AWS secret usage in the "Configure
AWS Credentials" step that uses aws-actions/configure-aws-credentials@v4 and the
keys aws-access-key-id/aws-secret-access-key with the recommended GitHub OIDC
settings: remove the static secret inputs and add role-to-assume (ARN of the IAM
role), role-session-name (optional), and aws-region; update the required-secrets
table/output docs to describe the IAM role and GitHub OIDC trust configuration
(instead of static key material). Also apply the same change to the other
occurrences of the "Configure AWS Credentials" step in this document so all
examples use OIDC/role-to-assume.

In `@docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx`:
- Around line 68-70: The table's default for gcpDiskSizeGb is invalid for
in-memory (currently `100` while max is 32); update the default value shown for
`gcpDiskSizeGb` to a valid in-memory size (e.g., `32`) in the
docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx table so the
documented default is achievable when using `in-memory` volumes and ensure the
cell still describes it as the in-memory volume size with max 32.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx`:
- Around line 105-115: The timeout table incorrectly documents `run-task` and
`watch-workflow` as "No limit"; update the table so the Timeout column matches
the implementation (replace "No limit" for `run-task` and `watch-workflow` with
the actual timeout values used by the codebase), and ensure the entries for
`run-task`, `watch-workflow`, and any related subcommands like `setup-workflow`,
`cleanup-workflow`, `garbage-collect`, `list-resources`, and `list-workflow`
precisely reflect the implementation to avoid misleading provider authors about
heartbeat/retry behavior.
- Around line 128-135: In the run-task branch, the script always echoes
'{"success": true ...}' regardless of the docker run outcome; modify the block
in the run-task handler to capture the docker run exit code and output (e.g.,
run the docker run and save its stdout/stderr and $? into variables), then emit
a JSON result where "success" is true only when the exit code is zero and
include the exit code and output in the JSON result; update the code around the
docker run invocation and the final echo that currently emits '{"success": true,
"result": "done"}' so it conditionally reflects the actual docker run result.
- Around line 157-159: The catch-all case (*) currently writes the
unknown-command JSON to stderr using the echo ... >&2 redirection, but the
protocol requires the final JSON be emitted on stdout; change the fallback in
the "*" case so the JSON error is echoed to stdout (remove the stderr
redirection) and then exit 1, ensuring the orchestrator receives the structured
response on stdout.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx`:
- Around line 241-251: The RUNNERS count logic uses the gh api call assigned to
the RUNNERS variable and incorrectly counts any online runners; update the jq
filter in the RUNNERS assignment (the gh api repos/${{ github.repository
}}/actions/runners --jq '...') to select idle runners by using select(.status ==
"online" and .busy == false) or the equivalent pattern used elsewhere
(select(.busy == false)) so the script only treats truly idle self-hosted
runners as available before writing provider=local-docker to GITHUB_OUTPUT.

In `@docs/03-github-orchestrator/08-cli/01-getting-started.mdx`:
- Around line 80-101: Re-check current CLI behavior for "game-ci build" and
update this onboarding section to reflect whether local Docker/native builds are
supported; if local/provider-strategy=local is unsupported, change the example
and text to show a supported provider (e.g., add a --provider-strategy aws or
--provider-strategy k8s example) or add a clear note that local builds are not
yet supported; ensure references to auto-detection of Unity version and the
example commands (the `game-ci build` invocation and the
`--unity-version`/`--target-platform` flags) are adjusted accordingly so the
documented "first build" flow matches actual behavior.

---

Nitpick comments:
In `@docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx`:
- Around line 86-107: The diagram and description currently present a WinRM-only
flow (uses Test-WSMan and PS-based credential creation) but claim SSH is
supported; update the text around the mermaid block to clarify that the diagram
illustrates the WinRM flow specifically and add a short note describing SSH
differences: state that Test-WSMan is not used for SSH, Invoke-Command should be
called with -HostName for SSH transport, and that credential handling differs
from the PScredential created from remotePowershellCredential; mention that SSH
connectivity verification (e.g., SSH key or password-based host reachability)
must occur instead of Test-WSMan.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e06775f6-35ff-4b40-921d-a64ebff9edd8

📥 Commits

Reviewing files that changed from the base of the PR and between a113d55 and 229a739.

📒 Files selected for processing (37)

• docs/03-github-orchestrator/01-introduction.mdx
• docs/03-github-orchestrator/03-examples/02-github-actions.mdx
• docs/03-github-orchestrator/03-examples/03-aws.mdx
• docs/03-github-orchestrator/03-examples/04-kubernetes.mdx
• docs/03-github-orchestrator/04-jobs.mdx
• docs/03-github-orchestrator/05-api-reference.mdx
• docs/03-github-orchestrator/05-providers/02-aws.mdx
• docs/03-github-orchestrator/05-providers/03-kubernetes.mdx
• docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx
• docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx
• docs/03-github-orchestrator/05-providers/05-local.mdx
• docs/03-github-orchestrator/05-providers/06-custom-providers.mdx
• docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx
• docs/03-github-orchestrator/05-providers/07-ansible.mdx
• docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx
• docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx
• docs/03-github-orchestrator/05-providers/11-azure-aci.mdx
• docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx
• docs/03-github-orchestrator/06-secrets.mdx
• docs/03-github-orchestrator/07-advanced-topics/01-caching.mdx
• docs/03-github-orchestrator/07-advanced-topics/02-retained-workspace.mdx
• docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx
• docs/03-github-orchestrator/07-advanced-topics/08-storage.mdx
• docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-lfs-agents.mdx
• docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx
• docs/03-github-orchestrator/07-advanced-topics/12-hot-runner-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx
• docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/15-massive-projects.mdx
• docs/03-github-orchestrator/07-advanced-topics/16-monorepo-support.mdx
• docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx
• docs/03-github-orchestrator/08-cli/01-getting-started.mdx
• docs/03-github-orchestrator/08-cli/02-build-command.mdx
• docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx
• docs/03-github-orchestrator/08-cli/04-other-commands.mdx

✅ Files skipped from review due to trivial changes (6)

• docs/03-github-orchestrator/07-advanced-topics/15-massive-projects.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx
• docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx
• docs/03-github-orchestrator/03-examples/04-kubernetes.mdx
• docs/03-github-orchestrator/04-jobs.mdx
• docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx

🚧 Files skipped from review as they are similar to previous changes (15)

• docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx
• docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx
• docs/03-github-orchestrator/05-providers/05-local.mdx
• docs/03-github-orchestrator/05-providers/02-aws.mdx
• docs/03-github-orchestrator/05-api-reference.mdx
• docs/03-github-orchestrator/07-advanced-topics/08-storage.mdx
• docs/03-github-orchestrator/05-providers/03-kubernetes.mdx
• docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx
• docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx
• docs/03-github-orchestrator/08-cli/04-other-commands.mdx
• docs/03-github-orchestrator/03-examples/03-aws.mdx
• docs/03-github-orchestrator/05-providers/07-ansible.mdx
• docs/03-github-orchestrator/05-providers/06-custom-providers.mdx
• docs/03-github-orchestrator/07-advanced-topics/16-monorepo-support.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-lfs-agents.mdx

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, locate and check the file exists
ls -la docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx 2>/dev/null && echo "File found" || echo "File not found"

# Check the file size to understand scope
wc -l docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx 2>/dev/null

Repository: game-ci/documentation

Length of output: 268

---

🏁 Script executed:

# Read the full file to understand the protocol documentation
cat -n docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx

Repository: game-ci/documentation

Length of output: 7203

---

Replace read request with request=$(cat) to handle multiline JSON payloads.

The protocol specifies a single JSON object on stdin with no requirement for single-line formatting. The documentation example shows pretty-printed JSON spanning multiple lines. The builtin read command stops at the first newline, so multiline JSON input would be truncated to just {, breaking subsequent jq parsing. Use request=$(cat) in all seven case branches to read the complete stdin payload.

Suggested change

   setup-workflow)
-    read request
+    request=$(cat)
     echo '{"success": true, "result": "ready"}'
     ;;
   run-task)
-    read request
+    request=$(cat)
     image=$(echo "$request" | jq -r '.params.image')
     commands=$(echo "$request" | jq -r '.params.commands')
     # Stream build output, then send JSON result
     docker run --rm "$image" /bin/sh -c "$commands" 2>&1
     echo '{"success": true, "result": "done"}'
     ;;
   cleanup-workflow)
-    read request
+    request=$(cat)
     echo '{"success": true, "result": "cleaned"}'
     ;;
   garbage-collect)
-    read request
+    request=$(cat)
     docker system prune -f >&2
     echo '{"success": true, "result": "pruned"}'
     ;;
   list-resources)
-    read request
+    request=$(cat)
     echo '{"success": true, "result": []}'
     ;;
   list-workflow)
-    read request
+    request=$(cat)
     echo '{"success": true, "result": []}'
     ;;
   watch-workflow)
-    read request
+    request=$(cat)
     echo '{"success": true, "result": ""}'
     ;;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 121 - 155, The example handler uses `read request` in each case branch
(setup-workflow, run-task, cleanup-workflow, garbage-collect, list-resources,
list-workflow, watch-workflow) which only reads up to the first newline and will
truncate multiline JSON; replace each `read request` with `request=$(cat)` so
the full stdin payload (potentially pretty-printed JSON) is captured before
using jq or docker run, ensuring jq -r '.params.*' and other JSON parsing
operate on the complete object.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Prefer short-lived AWS auth in the primary example.

The paragraph mentions IAM roles, but the only copy-paste example still normalizes long-lived access keys in GitHub secrets. Please make OIDC / assumed-role auth the primary path here and relegate static keys to a fallback note.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/06-secrets.mdx` around lines 43 - 53, Update the
example under secretSource: aws-secrets-manager to show short-lived
OIDC/assume-role auth as the primary pattern (e.g., reference GitHub
OIDC/configure-aws-credentials + role-to-assume and AWS_DEFAULT_REGION) and
remove the long-lived AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY as the main
copy-paste; instead move those two variables (AWS_ACCESS_KEY_ID,
AWS_SECRET_ACCESS_KEY) into a clearly labeled fallback note explaining static
keys are unsupported by default and should be avoided. Keep secretSource:
aws-secrets-manager and AWS_DEFAULT_REGION in the example so readers know which
fields remain required.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Missing builtClientPath field in Run Fields table.

The example at lines 141-148 uses builtClientPath: ./Builds/StandaloneLinux64, but this field is not documented in the Run Fields table.

📝 Proposed fix

 | `builtClient` | Run tests against a built client (default: false) |
+| `builtClientPath` | Path to the built client for `builtClient` runs |
 | `filters`     | Taxonomy filters to select tests                  |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx`
around lines 60 - 68, The Run Fields table is missing the builtClientPath field
used in examples; add a new table row documenting `builtClientPath`
(description: Path to the built client used when `builtClient: true`) alongside
the other fields in the Run Fields table so readers see the example's
`builtClientPath: ./Builds/StandaloneLinux64` is supported; update the table
near the existing `builtClient`/`filters`/`timeout` entries and ensure the field
name is formatted as `builtClientPath` to match the example.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

The page contradicts itself on whether these features are opt-in.

The intro says all reliability features are enabled via inputs, but the GIT_CONFIG_NOSYSTEM=1 section says that behavior is always applied automatically. Please narrow the intro to the configurable features, or call out the automatic Git hardening there as an exception.

Suggested wording

-Build reliability features harden CI builds against common failure modes: git corruption on
-persistent runners, Windows filesystem issues with cross-platform repositories, and build output
-management. All features are opt-in via action inputs and fail gracefully  -  a reliability check that
-encounters an error logs a warning rather than failing the build.
+Build reliability features harden CI builds against common failure modes: git corruption on
+persistent runners, Windows filesystem issues with cross-platform repositories, and build output
+management. Most features are opt-in via action inputs and fail gracefully  -  a reliability check
+that encounters an error logs a warning rather than failing the build. The Git environment hardening
+described below is applied automatically.

Also applies to: 169-174

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`
around lines 7 - 10, The intro currently states "All features are opt-in via
action inputs" but the "GIT_CONFIG_NOSYSTEM=1" section describes automatic Git
hardening; update the intro paragraph to say that most reliability features are
opt-in via action inputs while explicitly calling out that Git hardening
(referenced by the GIT_CONFIG_NOSYSTEM=1 section) is applied automatically as an
exception, and apply the same clarification to the later paragraph covering
lines 169-174 so the document no longer contradicts itself.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Clarify that recovery depends on an internal checkout phase, not a later workflow step.

"the checkout action completes the clone on the next step" reads like a later GitHub Actions step, which is confusing in a page that only shows unity-builder inputs. Reword this to point at the orchestrator's own checkout/sync phase so readers do not assume they need an extra post-build checkout.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`
around lines 51 - 56, The sentence "The checkout action completes the clone on
the next step" is ambiguous; update the wording to explicitly state that the
orchestrator's internal checkout/sync phase (not a later GitHub Actions workflow
step) will re-populate the repository immediately after re-initialization so
readers using the unity-builder inputs understand no extra post-build checkout
is required—replace the phrase with something like "the orchestrator's internal
checkout/sync phase will re-populate the repository immediately after
re-initialization" and ensure references to "checkout action" are clarified to
mean the orchestrator's own checkout step.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Document that archiving can remove the original build output path.

Because the archive step moves the build directory when it can, later workflow steps that upload artifacts from the usual build path will fail on same-device runners. Please explicitly say that enabling archival may relocate the only copy of the output and which path downstream steps should read from.

Suggested wording

 1. After a successful build, the build output directory is moved (or copied, if a cross-device move
    is not possible) to `{archivePath}/{platform}/build-{timestamp}`.
 2. Archives are organized by platform  -  each target platform gets its own subdirectory.
 3. The retention policy keeps the N most recent builds per platform. Older builds are automatically
    removed.
+
+If the archive is created via a same-filesystem move, the original build output path no longer
+exists afterward. Any later workflow step that consumes the build output should read from the
+archived path instead.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx`
around lines 135 - 142, Add a note stating that the archival step may move (not
just copy) the original build output, which can remove the usual build output
path on same-device runners; explicitly tell readers that downstream steps
should read artifacts from the archive location (use the
{archivePath}/{platform}/build-{timestamp} pattern) instead of the original
build output path when archival is enabled, and mention that cross-device moves
fall back to copying so behavior differs by runner.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# Search for "local-docker" mentions in the codebase
rg "local-docker" --type md --type mdx --type json --type js --type ts -i

Repository: game-ci/documentation

Length of output: 92

---

🏁 Script executed:

# Search for provider strategy definitions and documentation
rg "providerStrategy|provider-strategy" --type md --type mdx -A 3 -B 1

Repository: game-ci/documentation

Length of output: 92

---

🏁 Script executed:

# Check the orchestrate-command documentation referenced in the file
fd "orchestrate-command" --type f

Repository: game-ci/documentation

Length of output: 126

---

🏁 Script executed:

# Look for provider-related documentation files
fd "provider" --type f -path "*/docs/*"

Repository: game-ci/documentation

Length of output: 233

---

🏁 Script executed:

# Search for "local-docker" without file type restrictions
rg "local-docker" -i

Repository: game-ci/documentation

Length of output: 3245

---

🏁 Script executed:

# Search for provider strategy documentation without file type
rg "providerStrategy|provider.strategy" -A 3 -B 1

Repository: game-ci/documentation

Length of output: 50379

---

🏁 Script executed:

# Look at the orchestrate-command file that was found
cat "docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx"

Repository: game-ci/documentation

Length of output: 5959

---

🏁 Script executed:

# Find all files in the docs directory related to providers
fd "" "docs/03-github-orchestrator" -type f | head -20

Repository: game-ci/documentation

Length of output: 235

---

Add local-docker to the --provider-strategy description for consistency.

The local-docker provider is documented as a built-in strategy in the API reference and provider documentation, but this table omits it while the parallel orchestrate command includes it. This creates confusion about available options.

Suggested change

-| `--provider-strategy` | `local` | Execution strategy: `local`, `k8s`, or `aws` |
+| `--provider-strategy` | `local` | Execution strategy: `local`, `local-docker`, `k8s`, or `aws` |

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	## Provider Strategy
	By default, the `build` command runs locally. You can redirect execution to a remote orchestrator
	provider:
	| Flag | Default | Description |
	| --------------------- | ------- | -------------------------------------------- |
	| `--provider-strategy` | `local` | Execution strategy: `local`, `k8s`, or `aws` |
	When set to anything other than `local`, the build is handed off to the orchestrator. See
	[Orchestrate Command](orchestrate-command) for cloud-specific options.
	## Provider Strategy
	By default, the `build` command runs locally. You can redirect execution to a remote orchestrator
	provider:
	| Flag | Default | Description |
	| --------------------- | ------- | -------------------------------------------- |
	| `--provider-strategy` | `local` | Execution strategy: `local`, `local-docker`, `k8s`, or `aws` |
	When set to anything other than `local`, the build is handed off to the orchestrator. See
	[Orchestrate Command](orchestrate-command) for cloud-specific options.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/08-cli/02-build-command.mdx` around lines 116 -
126, Update the Provider Strategy table in the build command docs to include the
missing `local-docker` option: modify the description for `--provider-strategy`
(used by the `build` command) to list allowed values as `local`, `local-docker`,
`k8s`, or `aws` and add a short note that `local-docker` is a built-in strategy,
keeping the existing reference to [Orchestrate Command] for cloud-specific
options to ensure parity with the orchestrate command docs.

[coderabbitai]

Actionable comments posted: 9

♻️ Duplicate comments (9)

docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx (1)

18-22: ⚠️ Potential issue | 🟠 Major

Replace the legacy unity-builder CLI flow.

This example still sends readers through the old game-ci/unity-builder entrypoint and deprecated camelCase flags, which is out of sync with the standalone @game-ci/orchestrator CLI this PR is documenting. Please update the snippet to use the current orchestrator command surface.

Suggested doc update

   script:
-    - git clone https://github.com/game-ci/unity-builder.git /tmp/game-ci
-    - cd /tmp/game-ci && yarn install
     - >
-      yarn run cli -m cli-build --projectPath $CI_PROJECT_DIR --providerStrategy aws
-      --gitPrivateToken $GIT_TOKEN
+      game-ci orchestrate --project-path "$CI_PROJECT_DIR" --provider-strategy aws
+      --git-private-token "$GIT_TOKEN"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx` around
lines 18 - 22, Replace the legacy unity-builder snippet: stop calling the old
"game-ci/unity-builder" entrypoint and the camelCase flags used in "yarn run cli
-m cli-build" and instead invoke the current `@game-ci/orchestrator` CLI (e.g.,
via npx or yarn dlx) and switch all flags to kebab-case; update the example to
call the orchestrator build command (reference symbol: `@game-ci/orchestrator` and
the build action) and use flags like --project-path, --provider-strategy, and
--git-private-token in place of --projectPath, --providerStrategy, and
--gitPrivateToken so the docs reflect the new CLI surface.

docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx (4)

125-155: ⚠️ Potential issue | 🟠 Major

Use cat here so multiline JSON payloads are not truncated.

Bash read consumes a single line by default, but the protocol above explicitly allows pretty-printed JSON on stdin. A provider copied from this example would pass only the first line to jq for multiline requests. (gnu.org)

Suggested fix

-    read request
+    request=$(cat)

Apply the same change in each subcommand branch that currently uses read request.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 125 - 155, The subcommands (e.g., run-task, readied branch,
cleanup-workflow, garbage-collect, list-resources, list-workflow,
watch-workflow) currently use Bash read request which only reads a single line
and will truncate pretty-printed JSON; replace the single-line read usage with
reading the full stdin into the request variable (e.g., use cat to capture
multiline JSON) in each branch that currently calls read request so jq sees the
entire payload and not just the first line.

---

128-135: ⚠️ Potential issue | 🟠 Major

Only report success when docker run actually succeeds.

This example always emits {"success": true} even if the container exits non-zero. The CLI provider trusts that final JSON response to decide whether the task succeeded, so copied providers would silently mark failed builds as successful. (raw.githubusercontent.com)

Suggested fix

-    docker run --rm "$image" /bin/sh -c "$commands" 2>&1
-    echo '{"success": true, "result": "done"}'
+    if docker run --rm "$image" /bin/sh -c "$commands" 2>&1; then
+      echo '{"success": true, "result": "done"}'
+    else
+      exit_code=$?
+      echo "{\"success\": false, \"error\": \"Container exited with code ${exit_code}\"}"
+      exit "$exit_code"
+    fi

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 128 - 135, In the run-task case, the script always emits '{"success":
true}' regardless of the container exit status; change it so the exit code of
the docker run command is checked and the final JSON reflects success only when
that exit code is 0. Specifically, after resolving image and commands in the
run-task block, execute docker run and capture its exit code (from the docker
run invocation), then emit '{"success": true, "result": ...}' only when the exit
code is 0 and emit '{"success": false, "result": ...}' (including the exit code
or stderr message) when non-zero; update the code around the docker run
invocation and the final echo in the run-task case accordingly.

---

157-159: ⚠️ Potential issue | 🟠 Major

Write the structured error response to stdout, not stderr.

The implementation parses response JSON from stdout and forwards stderr to logs, so redirecting the unknown-command payload to stderr prevents the orchestrator from reading the structured failure response. (raw.githubusercontent.com)

Suggested fix

-    echo '{"success": false, "error": "Unknown command: '"$1"'"}' >&2
+    echo '{"success": false, "error": "Unknown command: '"$1"'"}'
     exit 1

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 157 - 159, The unknown-command branch currently writes the structured JSON
error to stderr; change it to write to stdout so the orchestrator can parse the
JSON response — i.e., modify the echo in that case (the line producing
'{"success": false, "error": "Unknown command: '"$1"'"}') to write to stdout
(remove the >&2 redirection) and keep the exit 1 so the process still returns a
failure code.

---

105-115: ⚠️ Potential issue | 🟠 Major

Document the enforced timeouts instead of “No limit”.

The CLI provider currently hardcodes run-task to 7,200,000 ms and watch-workflow to 3,600,000 ms, so this table and the sentence below it describe behavior the implementation does not allow. (raw.githubusercontent.com)

Suggested fix

 | `setup-workflow`   | Initialize infrastructure         | 300s     |
-| `run-task`         | Execute the build                 | No limit |
+| `run-task`         | Execute the build                 | 2h       |
 | `cleanup-workflow` | Tear down infrastructure          | 300s     |
 | `garbage-collect`  | Remove old resources              | 300s     |
 | `list-resources`   | List active resources             | 300s     |
 | `list-workflow`    | List active workflows             | 300s     |
-| `watch-workflow`   | Watch a workflow until completion | No limit |
+| `watch-workflow`   | Watch a workflow until completion | 1h       |
 
-`run-task` and `watch-workflow` have no timeout because builds can run for hours.
+`run-task` is limited to 2 hours and `watch-workflow` to 1 hour in the CLI provider implementation.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx` around
lines 105 - 115, Update the docs to reflect the actual enforced timeouts for the
CLI provider: replace "No limit" for `run-task` with "7,200,000 ms (2h)" and for
`watch-workflow` with "3,600,000 ms (1h)" in the table and change the following
sentence so it notes these enforced limits (use the millisecond values and
human-readable durations); reference the CLI subcommands `run-task` and
`watch-workflow` so readers can correlate the table to the implementation that
enforces those timeouts.

docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx (1)

241-247: ⚠️ Potential issue | 🟠 Major

Count idle runners here, not just online runners.

status == "online" still includes busy runners; GitHub's runner payload exposes busy separately, so this example can route to local-docker even when no self-hosted runner is actually free. (docs.github.com)

Suggested fix

-          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online")] | length')
+          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online" and .busy == false)] | length')

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx` around
lines 241 - 247, The RUNNERS count in the step with id "pick" currently counts
any runner with status == "online" and therefore includes busy runners; update
the GH API jq filter used in the RUNNERS assignment so it only counts runners
where status is "online" AND busy is false (i.e., idle), ensuring the workflow
routes to local-docker only when a self-hosted runner is actually free; modify
the RUNNERS assignment in that step accordingly while keeping GH_TOKEN and the
rest of the step intact.

docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx (2)

114-116: ⚠️ Potential issue | 🟠 Major

Narrow the HTTP warning to the auth methods that actually expose credentials.

This currently reads as if WinRM over HTTP always sends credentials in clear text. That is true for Basic auth, but not for Negotiate/Kerberos/NTLM or CredSSP, which provide message-level protection over HTTP. The note should distinguish those cases so readers do not get the wrong transport guidance.

Microsoft Learn WinRM HTTP Basic authentication cleartext Negotiate Kerberos NTLM CredSSP message encryption

Suggested doc tweak

-- **WinRM HTTPS** - For production use, configure WinRM over HTTPS (port 5986) with a valid TLS
-  certificate to encrypt traffic. The default HTTP transport (port 5985) sends credentials in clear
-  text over the network.
+- **WinRM transport security** - Prefer WinRM over HTTPS (port 5986) with a valid TLS certificate,
+  especially when using Basic authentication or when you need certificate-based host validation.
+  Over HTTP (5985), Basic authentication exposes credentials, while
+  Negotiate/Kerberos/NTLM and CredSSP provide message-level protection.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx` around
lines 114 - 116, Update the WinRM HTTP warning paragraph to clarify that only
Basic authentication sends credentials in clear text over HTTP; change the
sentence under the "WinRM HTTPS" bullet (the paragraph describing port 5985 vs
5986) to explicitly call out Basic auth as the insecure case and note that
Negotiate/Kerberos/NTLM and CredSSP provide message-level protection even over
HTTP, while still recommending WinRM over HTTPS (5986) with a valid TLS
certificate for production. Mention the relevant auth methods by name (Basic,
Negotiate/Kerberos/NTLM, CredSSP) so readers can distinguish which transports
expose credentials.

---

35-41: ⚠️ Potential issue | 🟠 Major

Move TrustedHosts guidance off the target and avoid *.

Line 40 configures the WinRM client trust list, so it does not belong in a “Target” setup snippet. Using TrustedHosts="*" here also disables host validation for every endpoint. Keep the target instructions to listener setup, then document client-side trust separately with explicit hosts or HTTPS.

Microsoft Learn WinRM TrustedHosts client setting wildcard security risk

Suggested doc tweak

 ### Enabling WinRM on the Target
 
 ```powershell
 # Run as Administrator on the target machine
 Enable-PSRemoting -Force
-Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*" -Force  # Or specific host

+If the orchestrator runner connects over WinRM HTTP to a non-domain host, configure
+WSMan:\localhost\Client\TrustedHosts on the runner/client with explicit hostnames only,
+or prefer WinRM over HTTPS (5986).

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx around
lines 35 - 41, The snippet configures the client-side TrustedHosts (Set-Item
WSMan:\localhost\Client\TrustedHosts) inside the "Target" setup; remove that
line from the target snippet and instead add a separate client/runner note
explaining to configure WSMan:\localhost\Client\TrustedHosts on the
orchestrator/runner (not the target) with explicit hostnames only (do not use
"*") or, preferably, use WinRM over HTTPS (port 5986) for non-domain hosts; keep
the target snippet limited to listener setup (e.g., Enable-PSRemoting) and place
the TrustedHosts guidance in a distinct client-side section.

</details>

</blockquote></details>
<details>
<summary>docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx (1)</summary><blockquote>

`58-68`: _⚠️ Potential issue_ | _🟡 Minor_

**Add `builtClientPath` to the Run Fields table.**

The example below uses `builtClientPath`, but the Run Fields table does not document it, so readers cannot tell that it is a supported field.
 

<details>
<summary>Suggested doc tweak</summary>

```diff
 | `editMode`    | Run Unity EditMode tests (default: false)         |
 | `playMode`    | Run Unity PlayMode tests (default: false)         |
 | `builtClient` | Run tests against a built client (default: false) |
+| `builtClientPath` | Path to the built client when `builtClient: true` |
 | `filters`     | Taxonomy filters to select tests                  |
 | `timeout`     | Maximum run duration in seconds                   |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx`
around lines 58 - 68, The Run Fields table is missing the builtClientPath entry
used in examples; add a new row in the “Run Fields” table with the field name
`builtClientPath` and a short description such as “Filesystem path to the built
client to run tests against (used when builtClient is true)”, keeping the same
table formatting and column style as the existing rows so examples and docs
match the supported fields.

🧹 Nitpick comments (1)

docs/03-github-orchestrator/05-providers/07-ansible.mdx (1)

227-229: Consider documenting security implications of writing secrets to disk.

Writing the vault password to /tmp/vault-pass on a shared runner means the secret is briefly accessible as a plaintext file. While the cleanup step mitigates this, you may want to add a note about this trade-off, especially for users on GitHub-hosted runners.

Optional: Consider suggesting mktemp for a unique filename to reduce collision risk:

- name: Write vault password
  run: |
    VAULT_PASS_FILE=$(mktemp)
    echo "${{ secrets.ANSIBLE_VAULT_PASSWORD }}" > "$VAULT_PASS_FILE"
    echo "VAULT_PASS_FILE=$VAULT_PASS_FILE" >> $GITHUB_ENV

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/07-ansible.mdx` around lines 227 -
229, The "Write vault password" step writes the secret to /tmp/vault-pass which
leaves plaintext on disk on shared runners; update the docs to explicitly call
out this security implication and recommend safer alternatives: use mktemp to
create a unique temp file, restrict file permissions (chmod 600) before writing,
export the temp filename to GITHUB_ENV if needed, and ensure an immediate
cleanup step to shred/remove the file; mention that GitHub-hosted runners are
shared and advise using in-memory approaches or GitHub Actions built-in secrets
masking where possible.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/03-github-orchestrator/04-jobs.mdx`:
- Around line 143-150: The docs show inconsistent YAML keys between the API
reference and examples: normalize on one key name (prefer the API reference's
singular "command" if that is the implemented schema) by updating all examples
(e.g., the preBuildSteps and postBuildSteps examples that currently use
"commands") to use "command" and ensure "image" remains present; then add a
short example demonstrating the "secrets" key in a postBuildSteps item (showing
how to list/reference secrets) and update the API reference text to match the
example so preBuildSteps, postBuildSteps, image, command, and secrets are
consistent across docs.

In `@docs/03-github-orchestrator/05-providers/02-aws.mdx`:
- Around line 28-50: Update the AWS credentials section to distinguish two
flows: Preferred OIDC role assumption (no long-lived secrets) and Fallback
long-lived access keys; explicitly mention that IAM roles assumed via OIDC do
not use AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY. Modify the GitHub Actions
example using aws-actions/configure-aws-credentials@v4 to show a role-to-assume
variant (include inputs like role-to-assume and optionally
role-session-name/role-duration-seconds) and keep a separate fallback example
showing aws-access-key-id and aws-secret-access-key for legacy users; ensure the
docs mention which environment variables are required for each path and label
the OIDC approach as recommended.

In `@docs/03-github-orchestrator/05-providers/03-kubernetes.mdx`:
- Around line 17-20: Update the "CPU and Memory" section to clarify that "1024 =
1 vCPU" is a provider-level convention rather than a native Kubernetes unit;
explicitly mention that Kubernetes native CPU units are millicores (e.g., 100m)
and memory uses binary SI suffixes (e.g., Mi, Gi), and note that the inputs
containerCpu and containerMemory follow the provider abstraction and are
translated to Kubernetes resource quantities. Reference the "CPU and Memory"
heading and the containerCpu/containerMemory inputs when making the text change
so readers understand it's an abstraction layer, not the upstream Kubernetes
format.

In `@docs/03-github-orchestrator/05-providers/07-ansible.mdx`:
- Around line 54-58: The example is passing the secret value directly to
ansibleVaultPassword even though that input expects a file path; update the
example so ansibleVaultPassword points to a filesystem path containing the vault
password (matching the "Full Workflow Example" approach). Concretely, change the
snippet around ansibleVaultPassword so it demonstrates writing the secret from
secrets.ANSIBLE_VAULT_PASSWORD (or secrets.ANSIBLE_VAULT_PASSWORD_FILE) into a
temporary file and then setting ansibleVaultPassword to that temp file path;
keep ansibleInventory and ansiblePlaybook as-is and reference the temp file path
in place of the current direct secret usage.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx`:
- Around line 243-245: The example uses GH_TOKEN (secrets.GITHUB_TOKEN) to call
the GET /repos/{owner}/{repo}/actions/runners endpoint which requires the
fine-grained Administration: Read permission; update the example job to either
add a job-level permissions block (permissions: administration: read) so
secrets.GITHUB_TOKEN will work, or explicitly document that a PAT or GitHub App
token with Administration (read) rights must be supplied instead of
secrets.GITHUB_TOKEN.
- Line 246: Update the RUNNERS lookup to paginate and count only idle online
runners: call gh api with --paginate when invoking the /actions/runners endpoint
and change the jq filter to select runners where .status == "online" and .busy
== false before taking the length (the existing RUNNERS=$(gh api ... --jq
'[.runners[] | select(.status == "online")] | length') should be adjusted to use
--paginate and include the .busy check).

In `@docs/03-github-orchestrator/07-advanced-topics/16-monorepo-support.mdx`:
- Around line 110-111: Update the sentence that mentions submoduleProfilePath to
narrow its scope to submodule git operations: replace "before any git
operations" with "before any submodule git operations" and keep the rest of the
sentence about initializing only the listed submodules and skipped submodules
never being cloned, fetched, or touched; refer to the symbol
submoduleProfilePath and the orchestrator behavior when making this wording
change.
- Around line 237-243: The PowerShell example in the "Validate submodule
profiles" run block uses bash-style backslashes and an OS-specific shell; change
the continuation characters to PowerShell backticks (`) for the multiline
command and switch the step's shell from "powershell" to "pwsh" for
cross-platform PowerShell Core compatibility while keeping the same parameters
(-ProfileDir config/submodule-profiles and -GitmodulesPath .gitmodules) and the
same script invocation name ("Validate submodule profiles").

In `@docs/03-github-orchestrator/08-cli/04-other-commands.mdx`:
- Around line 129-133: Update the CLI example output that currently reads
"game-ci (`@game-ci/orchestrator`) v3.0.0" to "game-ci (`@game-ci/orchestrator`)
v2.0.0" so the documentation example matches the LTS 2.0.0 release; locate the
code block showing the Node/Platform output (the triple-backtick example with
game-ci and Node.js) and replace the version string only.

---

Duplicate comments:
In `@docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx`:
- Around line 114-116: Update the WinRM HTTP warning paragraph to clarify that
only Basic authentication sends credentials in clear text over HTTP; change the
sentence under the "WinRM HTTPS" bullet (the paragraph describing port 5985 vs
5986) to explicitly call out Basic auth as the insecure case and note that
Negotiate/Kerberos/NTLM and CredSSP provide message-level protection even over
HTTP, while still recommending WinRM over HTTPS (5986) with a valid TLS
certificate for production. Mention the relevant auth methods by name (Basic,
Negotiate/Kerberos/NTLM, CredSSP) so readers can distinguish which transports
expose credentials.
- Around line 35-41: The snippet configures the client-side TrustedHosts
(Set-Item WSMan:\localhost\Client\TrustedHosts) inside the "Target" setup;
remove that line from the target snippet and instead add a separate
client/runner note explaining to configure WSMan:\localhost\Client\TrustedHosts
on the orchestrator/runner (not the target) with explicit hostnames only (do not
use "*") or, preferably, use WinRM over HTTPS (port 5986) for non-domain hosts;
keep the target snippet limited to listener setup (e.g., Enable-PSRemoting) and
place the TrustedHosts guidance in a distinct client-side section.

In `@docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx`:
- Around line 18-22: Replace the legacy unity-builder snippet: stop calling the
old "game-ci/unity-builder" entrypoint and the camelCase flags used in "yarn run
cli -m cli-build" and instead invoke the current `@game-ci/orchestrator` CLI
(e.g., via npx or yarn dlx) and switch all flags to kebab-case; update the
example to call the orchestrator build command (reference symbol:
`@game-ci/orchestrator` and the build action) and use flags like --project-path,
--provider-strategy, and --git-private-token in place of --projectPath,
--providerStrategy, and --gitPrivateToken so the docs reflect the new CLI
surface.

In `@docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx`:
- Around line 125-155: The subcommands (e.g., run-task, readied branch,
cleanup-workflow, garbage-collect, list-resources, list-workflow,
watch-workflow) currently use Bash read request which only reads a single line
and will truncate pretty-printed JSON; replace the single-line read usage with
reading the full stdin into the request variable (e.g., use cat to capture
multiline JSON) in each branch that currently calls read request so jq sees the
entire payload and not just the first line.
- Around line 128-135: In the run-task case, the script always emits
'{"success": true}' regardless of the container exit status; change it so the
exit code of the docker run command is checked and the final JSON reflects
success only when that exit code is 0. Specifically, after resolving image and
commands in the run-task block, execute docker run and capture its exit code
(from the docker run invocation), then emit '{"success": true, "result": ...}'
only when the exit code is 0 and emit '{"success": false, "result": ...}'
(including the exit code or stderr message) when non-zero; update the code
around the docker run invocation and the final echo in the run-task case
accordingly.
- Around line 157-159: The unknown-command branch currently writes the
structured JSON error to stderr; change it to write to stdout so the
orchestrator can parse the JSON response — i.e., modify the echo in that case
(the line producing '{"success": false, "error": "Unknown command: '"$1"'"}') to
write to stdout (remove the >&2 redirection) and keep the exit 1 so the process
still returns a failure code.
- Around line 105-115: Update the docs to reflect the actual enforced timeouts
for the CLI provider: replace "No limit" for `run-task` with "7,200,000 ms (2h)"
and for `watch-workflow` with "3,600,000 ms (1h)" in the table and change the
following sentence so it notes these enforced limits (use the millisecond values
and human-readable durations); reference the CLI subcommands `run-task` and
`watch-workflow` so readers can correlate the table to the implementation that
enforces those timeouts.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx`:
- Around line 241-247: The RUNNERS count in the step with id "pick" currently
counts any runner with status == "online" and therefore includes busy runners;
update the GH API jq filter used in the RUNNERS assignment so it only counts
runners where status is "online" AND busy is false (i.e., idle), ensuring the
workflow routes to local-docker only when a self-hosted runner is actually free;
modify the RUNNERS assignment in that step accordingly while keeping GH_TOKEN
and the rest of the step intact.

In `@docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx`:
- Around line 58-68: The Run Fields table is missing the builtClientPath entry
used in examples; add a new row in the “Run Fields” table with the field name
`builtClientPath` and a short description such as “Filesystem path to the built
client to run tests against (used when builtClient is true)”, keeping the same
table formatting and column style as the existing rows so examples and docs
match the supported fields.

---

Nitpick comments:
In `@docs/03-github-orchestrator/05-providers/07-ansible.mdx`:
- Around line 227-229: The "Write vault password" step writes the secret to
/tmp/vault-pass which leaves plaintext on disk on shared runners; update the
docs to explicitly call out this security implication and recommend safer
alternatives: use mktemp to create a unique temp file, restrict file permissions
(chmod 600) before writing, export the temp filename to GITHUB_ENV if needed,
and ensure an immediate cleanup step to shred/remove the file; mention that
GitHub-hosted runners are shared and advise using in-memory approaches or GitHub
Actions built-in secrets masking where possible.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 540a9bec-c429-451b-8b43-5fecc06530fa

📥 Commits

Reviewing files that changed from the base of the PR and between 229a739 and c05c4ed.

📒 Files selected for processing (37)

• docs/03-github-orchestrator/01-introduction.mdx
• docs/03-github-orchestrator/03-examples/02-github-actions.mdx
• docs/03-github-orchestrator/03-examples/03-aws.mdx
• docs/03-github-orchestrator/03-examples/04-kubernetes.mdx
• docs/03-github-orchestrator/04-jobs.mdx
• docs/03-github-orchestrator/05-api-reference.mdx
• docs/03-github-orchestrator/05-providers/02-aws.mdx
• docs/03-github-orchestrator/05-providers/03-kubernetes.mdx
• docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx
• docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx
• docs/03-github-orchestrator/05-providers/05-local.mdx
• docs/03-github-orchestrator/05-providers/06-custom-providers.mdx
• docs/03-github-orchestrator/05-providers/06-remote-powershell.mdx
• docs/03-github-orchestrator/05-providers/07-ansible.mdx
• docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx
• docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx
• docs/03-github-orchestrator/05-providers/11-azure-aci.mdx
• docs/03-github-orchestrator/05-providers/12-cli-provider-protocol.mdx
• docs/03-github-orchestrator/06-secrets.mdx
• docs/03-github-orchestrator/07-advanced-topics/01-caching.mdx
• docs/03-github-orchestrator/07-advanced-topics/02-retained-workspace.mdx
• docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx
• docs/03-github-orchestrator/07-advanced-topics/08-storage.mdx
• docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx
• docs/03-github-orchestrator/07-advanced-topics/10-lfs-agents.mdx
• docs/03-github-orchestrator/07-advanced-topics/11-test-workflow-engine.mdx
• docs/03-github-orchestrator/07-advanced-topics/12-hot-runner-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx
• docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/15-massive-projects.mdx
• docs/03-github-orchestrator/07-advanced-topics/16-monorepo-support.mdx
• docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx
• docs/03-github-orchestrator/08-cli/01-getting-started.mdx
• docs/03-github-orchestrator/08-cli/02-build-command.mdx
• docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx
• docs/03-github-orchestrator/08-cli/04-other-commands.mdx

✅ Files skipped from review due to trivial changes (2)

• docs/03-github-orchestrator/03-examples/04-kubernetes.mdx
• docs/03-github-orchestrator/05-providers/06-custom-providers.mdx

🚧 Files skipped from review as they are similar to previous changes (13)

• docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx
• docs/03-github-orchestrator/05-providers/05-gitlab-ci-dispatch.mdx
• docs/03-github-orchestrator/05-providers/11-azure-aci.mdx
• docs/03-github-orchestrator/05-providers/04-github-actions-dispatch.mdx
• docs/03-github-orchestrator/07-advanced-topics/09-architecture.mdx
• docs/03-github-orchestrator/05-api-reference.mdx
• docs/03-github-orchestrator/06-secrets.mdx
• docs/03-github-orchestrator/08-cli/01-getting-started.mdx
• docs/03-github-orchestrator/08-cli/03-orchestrate-command.mdx
• docs/03-github-orchestrator/07-advanced-topics/14-incremental-sync-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/15-massive-projects.mdx
• docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx
• docs/03-github-orchestrator/03-examples/03-aws.mdx

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for preBuildSteps/postBuildSteps schema definitions in the codebase
rg -n "preBuildSteps|postBuildSteps" --type yaml --type json -A 5
rg -n "commands|command" docs/03-github-orchestrator/ -B 2 -A 2 | head -80

Repository: game-ci/documentation

Length of output: 7501

---

🏁 Script executed:

#!/bin/bash
# Read the API reference file around line 60
echo "=== API Reference (lines 55-75) ==="
sed -n '55,75p' docs/03-github-orchestrator/05-api-reference.mdx

# Read the jobs.mdx file to see the preBuildSteps example
echo ""
echo "=== Jobs.mdx preBuildSteps example (lines 143-170) ==="
sed -n '143,170p' docs/03-github-orchestrator/04-jobs.mdx

Repository: game-ci/documentation

Length of output: 3238

---

Fix YAML key inconsistency in documentation.

The API reference (line 60) documents postBuildSteps with keys image, secrets, and command (singular), but the examples in this file use commands (plural) for both preBuildSteps and postBuildSteps. The architecture documentation also refers to commands (plural). Clarify which key name is correct and update the API reference and/or examples accordingly to ensure consistency.

Additionally, the API reference mentions secrets as a key for postBuildSteps, but neither example demonstrates its usage. Add documentation or an example showing how to use the secrets parameter if it is supported.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/04-jobs.mdx` around lines 143 - 150, The docs
show inconsistent YAML keys between the API reference and examples: normalize on
one key name (prefer the API reference's singular "command" if that is the
implemented schema) by updating all examples (e.g., the preBuildSteps and
postBuildSteps examples that currently use "commands") to use "command" and
ensure "image" remains present; then add a short example demonstrating the
"secrets" key in a postBuildSteps item (showing how to list/reference secrets)
and update the API reference text to match the example so preBuildSteps,
postBuildSteps, image, command, and secrets are consistent across docs.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

aws-actions configure-aws-credentials v4 GitHub Actions OIDC assume role IAM role access keys

💡 Result:

Recommended: GitHub Actions → AWS via OIDC (no long‑lived access keys)

1) In AWS IAM

• Create an OIDC identity provider for https://token.actions.githubusercontent.com (audience typically sts.amazonaws.com). [1]
• Create an IAM role whose trust policy allows sts:AssumeRoleWithWebIdentity from that provider and scopes access via OIDC claims (example below). [1]

Example trust policy (scope to a branch):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": "repo:<ORG>/<REPO>:ref:refs/heads/<BRANCH>"
      }
    }
  }]
}
``` [1]

- Attach the **permissions policy** to the role (least privilege for what your workflow must do). [1][2]

**2) In your GitHub workflow**
- Grant permission to request an OIDC token: `permissions: id-token: write`. [1]
- Use the action (v4) and provide `role-to-assume` + `aws-region`:

```yaml
permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>
          aws-region: us-east-1

      - run: aws sts get-caller-identity

This action exports standard AWS env vars (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION) for later steps. [3]

---

Alternative: Use IAM access keys (not recommended for CI)

If you must use long-lived keys, you can pass repository secrets like aws-access-key-id / aws-secret-access-key (and optionally still role-to-assume to assume a role). [1]

Best practice is OIDC to avoid storing access keys in GitHub. [1][2]

Sources: [1] aws-actions/configure-aws-credentials README, [2] AWS Security Blog (GitHub Actions ↔ IAM roles), [3] action overview describing exported env vars.

---

Fix IAM authentication guidance: distinguish between OIDC role assumption and long-lived access keys.

Lines 28–29 state "an IAM user or role" needs an access key and secret key, but IAM roles assumed via OIDC (the recommended approach) do not use long-lived credentials. The workflow example only demonstrates static secrets, which misleads GitHub Actions users away from the secure OIDC flow that configure-aws-credentials@v4 supports.

Separate the guidance into two paths:

• Preferred: IAM role assumable from GitHub Actions via OIDC (no stored secrets).
• Fallback: IAM user with long-lived access keys (for legacy workflows).

Update the example to show role-to-assume with OIDC instead of (or in addition to) the static-secret approach.

Suggested changes

-- An IAM user or role with an access key and secret key.
+- Either:
+  - an IAM role assumable from GitHub Actions via OIDC (preferred), or
+  - an IAM user with an access key and secret key.
@@
-If you're using GitHub Actions, configure credentials with:
+If you're using GitHub Actions, prefer OIDC + `role-to-assume`:
@@
 - name: Configure AWS Credentials
   uses: aws-actions/configure-aws-credentials@v4
   with:
-    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    role-to-assume: arn:aws:iam::123456789012:role/game-ci-orchestrator
     aws-region: eu-west-2

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/02-aws.mdx` around lines 28 - 50,
Update the AWS credentials section to distinguish two flows: Preferred OIDC role
assumption (no long-lived secrets) and Fallback long-lived access keys;
explicitly mention that IAM roles assumed via OIDC do not use
AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY. Modify the GitHub Actions example using
aws-actions/configure-aws-credentials@v4 to show a role-to-assume variant
(include inputs like role-to-assume and optionally
role-session-name/role-duration-seconds) and keep a separate fallback example
showing aws-access-key-id and aws-secret-access-key for legacy users; ensure the
docs mention which environment variables are required for each path and label
the OIDC approach as recommended.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

Kubernetes official docs CPU memory resource quantity format millicores Mi

💡 Result:

In Kubernetes, CPU and memory fields (for example resources.requests/limits) use the resource.Quantity format:

<quantity> ::= <signedNumber><suffix> where suffix can be decimal SI (m, k, M, G, T, P, E), binary SI (Ki, Mi, Gi, Ti, Pi, Ei), or a decimal exponent (e / E). Case matters. [2]

CPU (cores, millicores / millicpu)

• 1 CPU = 1 core (or 1 vCPU). [1]
• You can specify fractions as decimals or millicpu using m:
  • 0.1 CPU = 100m (often said as “100 millicores”). [1]
• Precision finer than 1m is not allowed. [1]

Memory (bytes, Mi / Gi, etc.)

• Memory is measured in bytes, with optional suffixes:
  • Decimal: k, M, G, T, P, E
  • Binary: Ki, Mi, Gi, Ti, Pi, Ei [1]
• Example equivalences Kubernetes gives: 129M ≈ 123Mi (different bases: 10³ vs 2¹⁰). [1]
• Suffix case matters: 400m memory is 0.4 bytes (not 400Mi). [1]

Sources: Kubernetes “Resource Management for Pods and Containers” doc (CPU millicores, memory units, case sensitivity) [1]; Kubernetes API “Quantity” definition (formal grammar and suffix sets) [2].

---

Clarify that 1024 = 1 vCPU is a provider convention, not a native Kubernetes unit.

The current wording misleads readers by implying Kubernetes itself accepts this format. Native Kubernetes resource quantities use millicores (m for CPU) and binary SI suffixes (Mi, Gi for memory), as documented in the Kubernetes official specification. The containerCpu / containerMemory inputs follow a provider-level abstraction.

Suggested edit

-Kubernetes accepts the same unit format as AWS - `1024 = 1 vCPU`, memory in MB. Do not include the
-vCPU or GB suffix.
+The Kubernetes provider uses the same `containerCpu` / `containerMemory` input convention as AWS:
+`1024 = 1 vCPU`, memory in MB. These are provider inputs, not raw Kubernetes resource quantities.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/03-kubernetes.mdx` around lines 17 -
20, Update the "CPU and Memory" section to clarify that "1024 = 1 vCPU" is a
provider-level convention rather than a native Kubernetes unit; explicitly
mention that Kubernetes native CPU units are millicores (e.g., 100m) and memory
uses binary SI suffixes (e.g., Mi, Gi), and note that the inputs containerCpu
and containerMemory follow the provider abstraction and are translated to
Kubernetes resource quantities. Reference the "CPU and Memory" heading and the
containerCpu/containerMemory inputs when making the text change so readers
understand it's an abstraction layer, not the upstream Kubernetes format.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Inconsistent vault password handling in example.

The configuration example passes secrets.ANSIBLE_VAULT_PASSWORD_FILE directly to ansibleVaultPassword, but this input expects a file path (as documented in the Inputs Reference table). The "Full Workflow Example" later correctly demonstrates writing the secret to a temporary file first.

Consider updating this example to be consistent with the recommended pattern:

📝 Suggested fix

     ansiblePlaybook: ./infrastructure/unity-build.yml
     ansibleExtraVars: '{"unity_version": "2022.3.0f1"}'
-    ansibleVaultPassword: ${{ secrets.ANSIBLE_VAULT_PASSWORD_FILE }}
+    # Note: ansibleVaultPassword expects a file path.
+    # See the "Full Workflow Example" section for the recommended
+    # pattern of writing the secret to a temporary file first.
+    ansibleVaultPassword: /tmp/vault-pass

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	ansibleInventory: ./infrastructure/inventory.yml
	ansiblePlaybook: ./infrastructure/unity-build.yml
	ansibleExtraVars: '{"unity_version": "2022.3.0f1"}'
	ansibleVaultPassword: ${{ secrets.ANSIBLE_VAULT_PASSWORD_FILE }}
	```
	ansibleInventory: ./infrastructure/inventory.yml
	ansiblePlaybook: ./infrastructure/unity-build.yml
	ansibleExtraVars: '{"unity_version": "2022.3.0f1"}'
	# Note: ansibleVaultPassword expects a file path.
	# See the "Full Workflow Example" section for the recommended
	# pattern of writing the secret to a temporary file first.
	ansibleVaultPassword: /tmp/vault-pass

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/05-providers/07-ansible.mdx` around lines 54 -
58, The example is passing the secret value directly to ansibleVaultPassword
even though that input expects a file path; update the example so
ansibleVaultPassword points to a filesystem path containing the vault password
(matching the "Full Workflow Example" approach). Concretely, change the snippet
around ansibleVaultPassword so it demonstrates writing the secret from
secrets.ANSIBLE_VAULT_PASSWORD (or secrets.ANSIBLE_VAULT_PASSWORD_FILE) into a
temporary file and then setting ansibleVaultPassword to that temp file path;
keep ansibleInventory and ansiblePlaybook as-is and reference the temp file path
in place of the current direct secret usage.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# First, find and read the file to understand the context
cat -n docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx | sed -n '230,260p'

Repository: game-ci/documentation

Length of output: 1233

---

🏁 Script executed:

#!/bin/bash
# Get more context around the lines in question
cat -n docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx | sed -n '200,280p'

Repository: game-ci/documentation

Length of output: 3110

---

🏁 Script executed:

#!/bin/bash
# Search for references to runners, self-hosted, or GH_TOKEN in the docs
rg -i "self-hosted.*runner|gh_token|github_token" docs/03-github-orchestrator/ -A 3 -B 3

Repository: game-ci/documentation

Length of output: 50379

---

🌐 Web query:

GitHub REST API self-hosted runners endpoint permissions fine-grained token requirements

💡 Result:

Fine‑grained PAT (FGPAT) permissions for self‑hosted runners REST endpoints (GitHub Actions)

Organization-level runner endpoints (/orgs/{org}/actions/runners/...)

• Read operations (e.g., get runner, list labels): Organization permission → “Self-hosted runners” = Read. [1]
• Write operations (e.g., create registration/remove token, delete runner, manage labels): Organization permission → “Self-hosted runners” = Write. [2]

Repository-level runner endpoints (/repos/{owner}/{repo}/actions/runners/...)

• Read operations (e.g., list runners, get runner, list runner downloads/labels): Repository permission → “Administration” = Read. [1]
• Write operations (e.g., create registration/remove token, delete runner, manage labels): Repository permission → “Administration” = Write. [1]

Quick check for the two most common endpoints

• POST /orgs/{org}/actions/runners/registration-token → Org: Self-hosted runners (Write). [2]
• POST /repos/{owner}/{repo}/actions/runners/registration-token → Repo: Administration (Write). [1]

Classic PAT comparison (often the source of confusion)

• Org runner endpoints typically require admin:org (and repo too if the relevant repo is private). [3]
• Repo runner endpoints typically require repo scope. [3]

Sources:
[1] GitHub Docs – “Permissions required for fine-grained personal access tokens” (lists runner endpoints and required repo permission/access). (docs.github.com)
[2] GitHub Docs – Self-hosted runners REST API (“Create a registration token for an organization” → FGPAT needs Self-hosted runners org permission (write)). (docs.github.com)
[3] GitHub Docs – Self-hosted runners REST API (classic PAT scope notes like admin:org / repo). (docs.github.com)

Citations:

• 1: https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens
• 2: https://docs.github.com/en/rest/actions/self-hosted-runners
• 3: https://docs.github.com/en/rest/actions/self-hosted-runners

---

Update the example to include required permissions or call out the PAT/App token requirement.

The endpoint GET /repos/{owner}/{repo}/actions/runners requires the fine-grained permission Administration: Read. The secrets.GITHUB_TOKEN provided by GitHub Actions has only contents: read and metadata: read by default and will fail without explicit configuration. Either add permissions: administration: read to the job, or update the example to document that users need a PAT or GitHub App token with Administration permissions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx` around
lines 243 - 245, The example uses GH_TOKEN (secrets.GITHUB_TOKEN) to call the
GET /repos/{owner}/{repo}/actions/runners endpoint which requires the
fine-grained Administration: Read permission; update the example job to either
add a job-level permissions block (permissions: administration: read) so
secrets.GITHUB_TOKEN will work, or explicitly document that a PAT or GitHub App
token with Administration (read) rights must be supplied instead of
secrets.GITHUB_TOKEN.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, let's check if the file exists and view the context around line 246
if [ -f "docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx" ]; then
  wc -l "docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx"
fi

Repository: game-ci/documentation

Length of output: 137

---

🏁 Script executed:

# View the context around line 246
sed -n '240,260p' "docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx"

Repository: game-ci/documentation

Length of output: 696

---

🌐 Web query:

GitHub API GET /repos/{owner}/{repo}/actions/runners pagination default limit

💡 Result:

For GET /repos/{owner}/{repo}/actions/runners (List self-hosted runners for a repository), pagination defaults are:

• per_page: 30 by default (max 100)
• page: 1 by default
  [1]

Source(s):
[1] (docs.github.com)

Citations:

• 1: https://docs.github.com/en/rest/actions/self-hosted-runners

---

🌐 Web query:

gh cli --paginate --slurp flags documentation actions runners

💡 Result:

--paginate and --slurp are flags for gh api (REST) and gh api graphql:

• --paginate: “Make additional HTTP requests to fetch all pages of results.” [1]
• --slurp: “Use with --paginate to return an array of all pages of either JSON arrays or objects” (i.e., wraps each page’s JSON response into one outer JSON array). [1]

Using them for GitHub Actions self-hosted runners

GitHub’s REST API endpoints include:

• List runners for an org: GET /orgs/{org}/actions/runners [2]
• List runners for a repo: GET /repos/{owner}/{repo}/actions/runners [2]

Examples:

# Org runners: fetch all pages, then flatten to one JSON array of runners
gh api /orgs/ORG/actions/runners --paginate --slurp \
  | jq '[.[].runners[]]'

# Repo runners
gh api /repos/OWNER/REPO/actions/runners --paginate --slurp \
  | jq '[.[].runners[]]'

If you don’t need --slurp, you can omit it and process each page as it streams. [1]

Sources: GitHub CLI gh api manual (flags + pagination behavior) [1]; GitHub REST API “self-hosted runners” endpoints [2].

---

Paginate the runner lookup for larger fleets.

GET /repos/{owner}/{repo}/actions/runners defaults to 30 results per page, and gh api only fetches later pages when --paginate is set. On repos with more than 30 runners, this sample can undercount available capacity and misroute builds. Additionally, the current query counts all online runners, including busy ones—you should filter for idle runners only. (docs.github.com)

Suggested fix

-          RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online")] | length')
+          RUNNERS=$(gh api --paginate --slurp repos/${{ github.repository }}/actions/runners \
+            --jq '[.[].runners[] | select(.status == "online" and .busy == false)] | length')

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	RUNNERS=$(gh api repos/${{ github.repository }}/actions/runners --jq '[.runners[] | select(.status == "online")] | length')
	RUNNERS=$(gh api --paginate --slurp repos/${{ github.repository }}/actions/runners \
	--jq '[.[].runners[] | select(.status == "online" and .busy == false)] | length')

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/07-load-balancing.mdx` at line
246, Update the RUNNERS lookup to paginate and count only idle online runners:
call gh api with --paginate when invoking the /actions/runners endpoint and
change the jq filter to select runners where .status == "online" and .busy ==
false before taking the length (the existing RUNNERS=$(gh api ... --jq
'[.runners[] | select(.status == "online")] | length') should be adjusted to use
--paginate and include the .busy check).

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Narrow this to submodule git operations.

The profile cannot be read before any git activity if it lives in the repository. “Before any submodule git operations” matches the behavior described here without overstating it.

Suggested wording

-When `submoduleProfilePath` is set, orchestrator reads the profile before any git operations and
+When `submoduleProfilePath` is set, orchestrator reads the profile before any submodule git operations and

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	When `submoduleProfilePath` is set, orchestrator reads the profile before any git operations and
	initializes only the listed submodules. Skipped submodules are never cloned, fetched, or touched.
	When `submoduleProfilePath` is set, orchestrator reads the profile before any submodule git operations and
	initializes only the listed submodules. Skipped submodules are never cloned, fetched, or touched.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/16-monorepo-support.mdx`
around lines 110 - 111, Update the sentence that mentions submoduleProfilePath
to narrow its scope to submodule git operations: replace "before any git
operations" with "before any submodule git operations" and keep the rest of the
sentence about initializing only the listed submodules and skipped submodules
never being cloned, fetched, or touched; refer to the symbol
submoduleProfilePath and the orchestrator behavior when making this wording
change.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Does GitHub Actions shell: powershellaccept` as a line continuation in run blocks, and is pwsh the recommended cross-platform PowerShell shell name?`

💡 Result:

No. In a GitHub Actions run: | block, the content is executed by the selected shell, so with shell: powershell (Windows PowerShell) a trailing \ is not a line-continuation character—PowerShell’s explicit line continuation is the backtick (`), and PowerShell also supports implicit continuation in syntactically “unfinished” constructs (e.g., inside (...), [...], {...}, after |, etc.). [2]

Yes. pwsh is the recommended cross-platform PowerShell shell name in GitHub Actions (PowerShell Core / PowerShell 7+), while powershell refers to Windows PowerShell (Desktop) and is Windows-only. GitHub’s shell table distinguishes pwsh (PowerShell Core) from powershell (PowerShell Desktop). [1]

Sources:
[1] GitHub Docs – workflow shell definitions (pwsh vs powershell) https://docs.github.com/fr/enterprise-server%403.16/actions/reference/github_token-reference
[2] Microsoft Learn – PowerShell parsing / backtick line continuation https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.4&viewFallbackFrom=powershell-7.2

---

Fix the PowerShell example before publishing.

This run block uses bash-style \ continuations, but PowerShell requires backticks (`) for line continuation. With shell: powershell, the example will fail. Additionally, use shell: pwsh for cross-platform compatibility (PowerShell Core) instead of powershell (Windows-only).

Suggested fix

 - name: Validate submodule profiles
   run: |
-    .\automation\ValidateSubmoduleProfiles.ps1 \
-      -ProfileDir config/submodule-profiles \
-      -GitmodulesPath .gitmodules
-  shell: powershell
+    ./automation/ValidateSubmoduleProfiles.ps1 `
+      -ProfileDir config/submodule-profiles `
+      -GitmodulesPath .gitmodules
+  shell: pwsh

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	```yaml
	- name: Validate submodule profiles
	run: |
	.\automation\ValidateSubmoduleProfiles.ps1 \
	-ProfileDir config/submodule-profiles \
	-GitmodulesPath .gitmodules
	shell: powershell

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/07-advanced-topics/16-monorepo-support.mdx`
around lines 237 - 243, The PowerShell example in the "Validate submodule
profiles" run block uses bash-style backslashes and an OS-specific shell; change
the continuation characters to PowerShell backticks (`) for the multiline
command and switch the step's shell from "powershell" to "pwsh" for
cross-platform PowerShell Core compatibility while keeping the same parameters
(-ProfileDir config/submodule-profiles and -GitmodulesPath .gitmodules) and the
same script invocation name ("Validate submodule profiles").

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

What is the latest version of @game-ci/orchestrator npm package?

💡 Result:

I couldn’t find any public npm package published under the name @game-ci/orchestrator, so there’s no “latest version” I can reliably report from the npm registry.

GameCI’s Orchestrator appears to be provided/used via GitHub Actions workflows (e.g., uses: game-ci/unity-builder@main) in their documentation rather than as an npm package. [1]

Sources:
[1] (game.ci)

Citations:

• 1: https://game.ci/docs/github-orchestrator/getting-started

---

🏁 Script executed:

# Read the specific file to see the full context
cat -n "docs/03-github-orchestrator/08-cli/04-other-commands.mdx" | sed -n '125,140p'

Repository: game-ci/documentation

Length of output: 510

---

🏁 Script executed:

# Search for version definitions in the repository
find . -type f \( -name "package.json" -o -name "version.json" -o -name "_version*" -o -name ".version*" \) | head -20

Repository: game-ci/documentation

Length of output: 1384

---

🏁 Script executed:

# Check if there's a version or changelog that indicates what version this PR is for
find . -type f \( -name "CHANGELOG*" -o -name "HISTORY*" -o -name "VERSION*" \) | head -20

Repository: game-ci/documentation

Length of output: 1072

---

🏁 Script executed:

# Check the documentation repository's package.json
cat package.json | grep -A 2 -B 2 '"version"'

Repository: game-ci/documentation

Length of output: 193

---

🏁 Script executed:

# Search for version references in the documentation
rg "v3\.0\.0|v2\.0\.0|3\.0\.0|2\.0\.0" --type mdx --type md docs/ | head -30

Repository: game-ci/documentation

Length of output: 92

---

🏁 Script executed:

# Check if there's a README or version file in the orchestrator references
find docs -type f -name "*.mdx" -o -name "*.md" | xargs rg "@game-ci/orchestrator" -l

Repository: game-ci/documentation

Length of output: 276

---

🏁 Script executed:

# Search for version numbers in orchestrator docs
rg "v3|v2|2\.0|3\.0" docs/03-github-orchestrator/ -A 2 -B 2

Repository: game-ci/documentation

Length of output: 10473

---

🏁 Script executed:

# Check orchestrator introduction/getting-started for version context
cat -n docs/03-github-orchestrator/01-introduction.mdx | head -50

Repository: game-ci/documentation

Length of output: 2688

---

🏁 Script executed:

# Search for any LTS or version release information in docs
rg "LTS|release|version" docs/03-github-orchestrator/ | head -20

Repository: game-ci/documentation

Length of output: 2587

---

Update the example CLI version output to match the LTS 2.0.0 release.

The example at line 130 shows v3.0.0, but other documentation examples and this PR target LTS 2.0.0. Change the version output example to v2.0.0 for consistency.

Reference: Other version examples in the documentation

• GAME_CI_VERSION=v2.0.0 in CLI getting-started guide
• Update command example shows v2.1.0

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/08-cli/04-other-commands.mdx` around lines 129 -
133, Update the CLI example output that currently reads "game-ci
(`@game-ci/orchestrator`) v3.0.0" to "game-ci (`@game-ci/orchestrator`) v2.0.0" so
the documentation example matches the LTS 2.0.0 release; locate the code block
showing the Node/Platform output (the triple-backtick example with game-ci and
Node.js) and replace the version string only.

[coderabbitai]

♻️ Duplicate comments (1)

docs/03-github-orchestrator/03-examples/01-command-line.mdx (1)

70-78: ⚠️ Potential issue | 🟠 Major

Point this example at the current secrets flow.

Line 71 still links to a fragment that does not exist in docs/03-github-orchestrator/06-secrets.mdx, and Lines 76-78 still demonstrate the legacy inputPullCommand path instead of the recommended secretSource flow. As written, this section will both fail the internal-link check and send readers to an outdated example.

Suggested update

-Avoid long CLI flags for credentials by using environment variables or the
-[Pull Secrets](../secrets#-pulling-secrets-from-external-sources) feature:
+Avoid long CLI flags for credentials by using environment variables or the
+[Secrets](../secrets) feature:

 game-ci build \
   --target-platform StandaloneLinux64 \
-  --populate-override true \
+  --secret-source gcp-secret-manager \
   --pull-input-list UNITY_EMAIL,UNITY_SERIAL,UNITY_PASSWORD \
-  --input-pull-command='gcloud secrets versions access 1 --secret="{0}"'

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/03-github-orchestrator/03-examples/01-command-line.mdx` around lines 70
- 78, Update the "Pull Secrets" link to point at the current secrets
documentation fragment (the canonical Pull Secrets section) and replace the
legacy inputPullCommand example with the recommended secretSource flow: remove
usage of the deprecated inputPullCommand pattern and instead show using
--pull-input-list together with the secretSource configuration (referencing the
secretSource parameter name) so the example matches the current secrets flow and
the internal-link check.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@docs/03-github-orchestrator/03-examples/01-command-line.mdx`:
- Around line 70-78: Update the "Pull Secrets" link to point at the current
secrets documentation fragment (the canonical Pull Secrets section) and replace
the legacy inputPullCommand example with the recommended secretSource flow:
remove usage of the deprecated inputPullCommand pattern and instead show using
--pull-input-list together with the secretSource configuration (referencing the
secretSource parameter name) so the example matches the current secrets flow and
the internal-link check.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0ab57570-8447-4507-9741-8f04160ee986

📥 Commits

Reviewing files that changed from the base of the PR and between c05c4ed and 6f04c03.

📒 Files selected for processing (1)

• docs/03-github-orchestrator/03-examples/01-command-line.mdx

[frostebite]

Engine plugin documentation added via #544 (now merged into this branch). Covers the new EnginePlugin interface, plugin sources (npm, CLI, Docker), and updates to introduction, caching, API reference, and CLI docs. Related orchestrator PR: game-ci/orchestrator#4