Skip to content

Commit c95128d

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

29 files changed

Lines changed: 222 additions & 169 deletions

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

Lines changed: 21 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ be built, and streams results back.
1818
│ Orchestrator handles: │
1919
│ • Provisioning │
2020
│ • Git sync + LFS │
21-
│ • Caching │
22-
│ • Cleanup │
21+
│ • Caching (S3 / rclone) │
22+
│ • Automatic cleanup │
2323
└─────────────────────────────────────┘
2424
```
2525

@@ -30,42 +30,35 @@ AWS Fargate and Kubernetes.
3030

3131
1. **Flexible and elastic** — balance speed and cost, configure CPU, memory, and disk per build
3232
2. **Scale from zero** — no idle servers, pay only while builds run
33-
3. **Easy setup** — minimal configuration to get started
34-
4. **Extensible** — run custom jobs, add hooks, or bring your own provider via the plugin system
33+
3. **Easy setup** — minimal configuration to [get started](getting-started)
34+
4. **Extensible** — run [custom hooks](advanced-topics/hooks), or bring your own
35+
[provider plugin](providers/custom-providers)
3536

3637
## ❌ When You Don't Need It
3738

3839
- Your project is under 5 GB — standard GitHub runners should work fine
3940
- You have dedicated build servers already running
4041

41-
## 📦 Release Status
42+
## 📦 Supported Providers
4243

43-
Orchestrator is in **active development** ⚠️
44+
| Cloud Provider | Description |
45+
| -------------------------------------- | -------------------------------------------------------- |
46+
| [AWS Fargate](providers/aws) | Fully managed containers on AWS. No servers to maintain. |
47+
| [Kubernetes](providers/kubernetes) | Run on any Kubernetes cluster. |
48+
| [Local Docker](providers/local-docker) | Docker containers on the local machine. |
49+
| [Local](providers/local) | Direct execution on the host machine. |
4450

45-
Overall status: `preview` — core features are stable, some APIs may change.
51+
See [Providers](providers/overview) for the full list including [custom](providers/custom-providers)
52+
and [community](providers/community-providers) providers.
4653

47-
Release stages: `experimental` → `preview` → `full release`
54+
## 🖥️ Supported Platforms
4855

49-
### Provider Support
50-
51-
| Cloud Provider | Release Status |
52-
| -------------- | ------------------ |
53-
| AWS Fargate | ✔️ Full release |
54-
| Kubernetes | ✔️ Preview release |
55-
| GCP | ⚠️ Considered |
56-
| Azure | ⚠️ Considered |
57-
58-
See [Providers](advanced-topics/providers/overview) for details on each provider.
59-
60-
### Platform Support
61-
62-
| Platform | Release Status |
63-
| ------------------ | ------------------ |
64-
| GitHub Actions | ✔️ Full release |
65-
| GitLab CI | ✔️ Preview release |
66-
| Command Line | ✔️ Preview release |
67-
| Any Git repository | ✔️ Preview release |
68-
| Any CI system | ✔️ Preview release |
56+
| Platform | Description |
57+
| ---------------------------------------------- | ------------------------------------- |
58+
| [GitHub Actions](providers/github-integration) | First-class support with Checks. |
59+
| [GitLab CI](providers/gitlab-integration) | Via the Command Line mode. |
60+
| [Command Line](examples/command-line) | Run from any terminal or script. |
61+
| Any CI system | Anything that can run shell commands. |
6962

7063
## 🔗 External Links
7164

‎docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
sidebar_label: Game-CI vs Orchestrator
3+
---
4+
15
# Standard Game-CI vs Orchestrator Mode
26

37
## 🎮 Standard Game-CI
@@ -20,10 +24,11 @@ the CI runner itself. This is useful when:
2024
Standard Game-CI Orchestrator Mode
2125
2226
┌──────────────┐ ┌──────────────┐ ┌────────────┐
23-
│ GitHub │ │ GitHub │ ───► │ Cloud │
24-
│ Runner │ │ Runner │ │ Container │
25-
│ (builds │ │ (dispatches │ ◄─── │ (builds │
26-
│ locally) │ │ only) │ │ remotely) │
27+
│ GitHub │ │ GitHub Action │ │ │
28+
│ Runner │ │ CLI / Any CI │ ───► │ Cloud │
29+
│ (builds │ │ │ │ Container │
30+
│ locally) │ │ (dispatches │ ◄─── │ (builds │
31+
│ │ │ only) │ │ remotely) │
2732
└──────────────┘ └──────────────┘ └────────────┘
2833
~14 GB disk Configurable CPU, memory, disk
2934
Fixed resources Scales to zero when idle

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,19 @@ runners. This is useful for large projects that exceed GitHub's disk or resource
77

88
- A Unity project in a GitHub repository
99
- A cloud provider account (AWS or a Kubernetes cluster)
10-
- Provider credentials configured as GitHub secrets
10+
- Provider credentials configured as GitHub [secrets](secrets)
1111

1212
## Quick Start
1313

1414
1. **Choose a provider**: `aws` (AWS Fargate) or `k8s` (Kubernetes)
1515
2. **Configure credentials** for your chosen provider
1616
3. **Add the orchestrator step** to your workflow
1717

18-
See the provider-specific examples for complete setup:
18+
See the provider-specific setup guides:
1919

20-
- [AWS Example](examples/github-examples/aws)
21-
- [Kubernetes Example](examples/github-examples/kubernetes)
20+
- [AWS Fargate](providers/aws)
21+
- [Kubernetes](providers/kubernetes)
22+
- [Local Docker](providers/local-docker)
2223
- [Command Line](examples/command-line)
2324

2425
## Minimal Example

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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# Command Line
22

3-
_Preview Support Only_
4-
53
You can install Game CI locally and start orchestrator jobs from the command line or by integrating
64
your own tools. All parameters in the [API Reference](../api-reference) can be specified as CLI
75
flags.

‎docs/03-github-orchestrator/03-examples/02-github-examples/_category_.yaml‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/03-github-orchestrator/04-api-reference.mdx‎

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -31,13 +31,13 @@ Set the mode to control what Orchestrator does. Default: `cli-build`.
3131

3232
### Provider
3333

34-
| Parameter | Default | Description |
35-
| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36-
| `providerStrategy` | `local` | Cloud provider to use. Built-in: `aws`, `k8s`, `local-docker`, `local`. Also accepts a GitHub URL, NPM package, or local path for [custom providers](advanced-topics/providers/custom-providers). |
37-
| `containerCpu` | `1024` | CPU units for cloud containers (`1024` = 1 vCPU). See provider setup guides for allowed values. |
38-
| `containerMemory` | `3072` | Memory in MB for cloud containers (`4096` = 4 GB). See provider setup guides for allowed values. |
39-
| `orchestratorBranch` | `main` | Release branch of Orchestrator for remote containers. Use `orchestrator-develop` for latest development builds. |
40-
| `orchestratorRepoName` | `game-ci/unity-builder` | Repository for Orchestrator source. Override to use a fork for testing or custom builds. |
34+
| Parameter | Default | Description |
35+
| ---------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36+
| `providerStrategy` | `local` | Cloud provider to use. Built-in: `aws`, `k8s`, `local-docker`, `local`. Also accepts a GitHub URL, NPM package, or local path for [custom providers](providers/custom-providers). |
37+
| `containerCpu` | `1024` | CPU units for cloud containers (`1024` = 1 vCPU). See provider setup guides for allowed values. |
38+
| `containerMemory` | `3072` | Memory in MB for cloud containers (`4096` = 4 GB). See provider setup guides for allowed values. |
39+
| `orchestratorBranch` | `main` | Release branch of Orchestrator for remote containers. Use `orchestrator-develop` for latest development builds. |
40+
| `orchestratorRepoName` | `game-ci/unity-builder` | Repository for Orchestrator source. Override to use a fork for testing or custom builds. |
4141

4242
### Git Synchronization
4343

@@ -52,16 +52,16 @@ Set the mode to control what Orchestrator does. Default: `cli-build`.
5252

5353
### Custom Hooks
5454

55-
| Parameter | Default | Description |
56-
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
57-
| `containerHookFiles` | — | Names of [container hook](advanced-topics/custom-hooks/container-hooks) files from `.game-ci/container-hooks/`. |
58-
| `customHookFiles` | — | Names of custom hook files from `.game-ci/hooks/`. |
59-
| `customCommandHooks` | — | Inline [command hooks](advanced-topics/custom-hooks/command-hooks) as YAML. |
60-
| `postBuildSteps` | — | Post-build job in YAML format with keys: `image`, `secrets`, `command`. |
61-
| `preBuildSteps` | — | Pre-build job (after repo setup, before build) in YAML format. |
62-
| `postBuildContainerHooks` | — | Container hook files to run after the build step. |
63-
| `preBuildContainerHooks` | — | Container hook files to run before the build step. |
64-
| `customJob` | — | Custom job YAML to override the default build workflow. See [Custom Job](advanced-topics/custom-hooks/custom-job). |
55+
| Parameter | Default | Description |
56+
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
57+
| `containerHookFiles` | — | Names of [container hook](advanced-topics/hooks/container-hooks) files from `.game-ci/container-hooks/`. |
58+
| `customHookFiles` | — | Names of custom hook files from `.game-ci/hooks/`. |
59+
| `customCommandHooks` | — | Inline [command hooks](advanced-topics/hooks/command-hooks) as YAML. |
60+
| `postBuildSteps` | — | Post-build job in YAML format with keys: `image`, `secrets`, `command`. |
61+
| `preBuildSteps` | — | Pre-build job (after repo setup, before build) in YAML format. |
62+
| `postBuildContainerHooks` | — | Container hook files to run after the build step. |
63+
| `preBuildContainerHooks` | — | Container hook files to run before the build step. |
64+
| `customJob` | — | Custom job YAML to override the default build workflow. See [Custom Job](advanced-topics/hooks/custom-job). |
6565

6666
### Configuration Override
6767

@@ -72,10 +72,10 @@ Set the mode to control what Orchestrator does. Default: `cli-build`.
7272

7373
### Storage
7474

75-
| Parameter | Default | Description |
76-
| ----------------- | ------- | --------------------------------------------------------------------------- |
77-
| `storageProvider` | `s3` | Storage backend for caching and artifacts. Accepted values: `s3`, `rclone`. |
78-
| `rcloneRemote` | — | Rclone remote endpoint. Required when `storageProvider` is `rclone`. |
75+
| Parameter | Default | Description |
76+
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------ |
77+
| `storageProvider` | `s3` | Storage backend for [caching](advanced-topics/caching) and artifacts. Accepted values: `s3`, `rclone`. |
78+
| `rcloneRemote` | — | Rclone remote endpoint. Required when `storageProvider` is `rclone`. |
7979

8080
### AWS
8181

@@ -107,11 +107,11 @@ Set the mode to control what Orchestrator does. Default: `cli-build`.
107107

108108
### GitHub Integration
109109

110-
| Parameter | Default | Description |
111-
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
112-
| `githubCheck` | `false` | Create a GitHub Check for each orchestrator step. See [GitHub Integration](advanced-topics/providers/github-integration). |
113-
| `asyncOrchestrator` | `false` | Run in async mode — returns immediately without waiting for the build to complete. |
114-
| `watchToEnd` | `true` | Whether to follow the build logs until completion. |
110+
| Parameter | Default | Description |
111+
| ------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
112+
| `githubCheck` | `false` | Create a GitHub Check for each orchestrator step. See [GitHub Integration](providers/github-integration). |
113+
| `asyncOrchestrator` | `false` | Run in async mode — returns immediately without waiting for the build to complete. |
114+
| `watchToEnd` | `true` | Whether to follow the build logs until completion. |
115115

116116
### Build Options
117117

‎docs/03-github-orchestrator/05-providers/01-overview.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Providers
2+
3+
A **provider** is the backend that Orchestrator uses to run your builds. You choose a provider by
4+
setting the `providerStrategy` parameter.
5+
6+
## Built-in Providers
7+
8+
These providers ship with Orchestrator and are maintained by the Game CI team.
9+
10+
| Provider | `providerStrategy` | Description |
11+
| -------------- | ------------------ | ----------------------------------------------------------------------------- |
12+
| AWS Fargate | `aws` | Runs jobs on AWS Fargate (ECS). Fully managed, no servers to maintain. |
13+
| Kubernetes | `k8s` | Runs jobs on any Kubernetes cluster. Flexible but requires a running cluster. |
14+
| Local Docker | `local-docker` | Runs jobs in Docker containers on the local machine. |
15+
| Local (direct) | `local` | Runs jobs directly on the local machine without containers. |
16+
17+
Each provider has its own page with setup instructions:
18+
19+
- [AWS Fargate](aws)
20+
- [Kubernetes](kubernetes)
21+
- [Local Docker](local-docker)
22+
- [Local](local)
23+
24+
## Custom Providers
25+
26+
Extend Orchestrator with your own provider by pointing `providerStrategy` at a GitHub repository,
27+
NPM package, or local file path.
28+
29+
See [Custom Providers](custom-providers) for the full guide.
30+
31+
## Community Providers
32+
33+
Third-party providers shared by the Game CI community.
34+
35+
See the [Community Providers](community-providers) page for the current list and how to submit your
36+
own.

docs/03-github-orchestrator/03-examples/02-github-examples/02-aws.mdx renamed to docs/03-github-orchestrator/05-providers/02-aws.mdx

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,13 +62,12 @@ Common combinations:
6262
containerHookFiles: aws-s3-upload-build
6363
```
6464

65-
See [Container Hooks](../../advanced-topics/custom-hooks/container-hooks) for more on
66-
`containerHookFiles`.
65+
See [Container Hooks](../advanced-topics/hooks/container-hooks) for more on `containerHookFiles`.
6766

6867
A full workflow example is available in the builder source:
6968
[orchestrator-pipeline.yml](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/orchestrator-pipeline.yml).
7069

7170
## AWS Parameters
7271

7372
For the full list of AWS-specific parameters (`awsStackName`, endpoint overrides, etc.), see the
74-
[API Reference — AWS section](../../api-reference#aws).
73+
[API Reference — AWS section](../api-reference#aws).

docs/03-github-orchestrator/03-examples/02-github-examples/03-kubernetes.mdx renamed to docs/03-github-orchestrator/05-providers/03-kubernetes.mdx

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,7 @@ vCPU or GB suffix.
4646
containerHookFiles: aws-s3-upload-build
4747
```
4848

49-
See [Container Hooks](../../advanced-topics/custom-hooks/container-hooks) for more on
50-
`containerHookFiles`.
49+
See [Container Hooks](../advanced-topics/hooks/container-hooks) for more on `containerHookFiles`.
5150

5251
A full workflow example is available in the builder source:
5352
[orchestrator-k8s-pipeline.yml](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/orchestrator-k8s-pipeline.yml).
@@ -56,10 +55,10 @@ A full workflow example is available in the builder source:
5655

5756
- **Keep the cluster running.** Cold-starting a Kubernetes cluster is slow. If you need auto-scaling
5857
to zero, consider Google Cloud Kubernetes Autopilot.
59-
- **Cloud storage required.** Kubernetes support currently requires cloud storage for caching. S3 is
60-
built-in, or use rclone for other backends.
58+
- **Cloud storage required.** Kubernetes requires cloud storage for
59+
[caching](../advanced-topics/caching). S3 is built-in, or use rclone for other backends.
6160

6261
## K8s Parameters
6362

6463
For the full list of Kubernetes parameters (`kubeConfig`, `kubeVolume`, `kubeStorageClass`, etc.),
65-
see the [API Reference — Kubernetes section](../../api-reference#kubernetes).
64+
see the [API Reference — Kubernetes section](../api-reference#kubernetes).

‎docs/03-github-orchestrator/05-providers/04-local-docker.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Local Docker
2+
3+
Runs the build workflow inside a Docker container on the local machine. No cloud account required.
4+
5+
## Requirements
6+
7+
- Docker installed and running on the build machine.
8+
9+
## Example Workflow
10+
11+
### GitHub Actions (self-hosted runner)
12+
13+
```yaml
14+
- uses: game-ci/unity-builder@v4
15+
with:
16+
providerStrategy: local-docker
17+
targetPlatform: StandaloneLinux64
18+
gitPrivateToken: ${{ secrets.GITHUB_TOKEN }}
19+
```
20+
21+
### Command Line
22+
23+
```bash
24+
yarn run cli -m cli-build \
25+
--providerStrategy local-docker \
26+
--projectPath /path/to/your/project \
27+
--targetPlatform StandaloneLinux64
28+
```
29+
30+
## When to Use
31+
32+
- You have a self-hosted runner with Docker installed
33+
- You want container isolation without cloud infrastructure
34+
- Testing builds locally before deploying to AWS or Kubernetes

0 commit comments

Comments
 (0)