Skip to content

Commit 2321c1e

Browse files
frostebiteclaude
frostebite
and
claude
committed
docs(providers): add GCP Cloud Run and Azure ACI provider documentation
Covers storage type comparison tables, inputs, examples, and cross-links to related providers. Both marked as experimental. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 7b370f1 commit 2321c1e

2 files changed

Lines changed: 233 additions & 0 deletions

File tree

‎docs/03-github-orchestrator/05-providers/10-gcp-cloud-run.mdx‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# GCP Cloud Run (Experimental)
2+
3+
Run Unity builds as [Cloud Run Jobs](https://cloud.google.com/run/docs/create-jobs) — one-off
4+
serverless container executions with configurable storage backends.
5+
6+
:::caution Experimental
7+
This provider is experimental. APIs and behavior may change between releases.
8+
:::
9+
10+
```
11+
GitHub Actions Runner
12+
┌──────────────────────────┐
13+
│ unity-builder │
14+
│ providerStrategy: │ gcloud CLI
15+
│ gcp-cloud-run │────────────────► Cloud Run Jobs API
16+
│ │ ┌─────────────────┐
17+
│ gcpStorageType: │ │ Job: unity-build│
18+
│ gcs-fuse / gcs-copy / │ │ │
19+
│ nfs / in-memory │ │ Image: unityci │
20+
│ │ │ Storage: ... │
21+
└──────────────────────────┘ └─────────────────┘
22+
```
23+
24+
## Prerequisites
25+
26+
- Google Cloud SDK installed and authenticated (`gcloud auth login` or `GOOGLE_APPLICATION_CREDENTIALS`)
27+
- Cloud Run Jobs API enabled: `gcloud services enable run.googleapis.com`
28+
- Service account with roles: **Cloud Run Admin**, **Storage Admin**, **Logs Viewer**
29+
30+
## Storage Types
31+
32+
Set `gcpStorageType` to control how the build accesses large files. Each type has different
33+
trade-offs for performance, persistence, and complexity.
34+
35+
| Type | How it works | Best for | Size limit |
36+
| ----------- | ------------------------------------------------- | ----------------------------------- | ---------- |
37+
| `gcs-fuse` | Mounts a GCS bucket as a POSIX filesystem via FUSE | Large sequential I/O, artifacts | Unlimited |
38+
| `gcs-copy` | Copies artifacts in/out via `gsutil` | Simple upload/download | Unlimited |
39+
| `nfs` | Mounts a Filestore instance as NFS share | Unity Library (small random reads) | 100 TiB |
40+
| `in-memory` | tmpfs volume inside the container | Scratch/temp during builds | 32 GiB |
41+
42+
### When to use each type
43+
44+
- **gcs-fuse** (default) — Good general-purpose option. Handles very large files well and persists
45+
across builds. Has some latency on small file I/O and eventual consistency edge cases.
46+
47+
- **gcs-copy** — Simpler than FUSE (no driver). Copies everything before the build starts and uploads
48+
after it finishes. Best when you only need artifact upload/download, not live filesystem access
49+
during the build.
50+
51+
- **nfs** — True POSIX semantics with good random I/O performance. The best choice for caching the
52+
Unity Library folder (thousands of small files). Requires a
53+
[Filestore](https://cloud.google.com/filestore) instance and a VPC connector.
54+
55+
- **in-memory** — Fastest option (RAM-backed). Data is lost when the job ends. Capped at 32 GiB.
56+
Use for temporary build artifacts that don't need to persist.
57+
58+
## Inputs
59+
60+
| Input | Default | Description |
61+
| ------------------ | ---------------- | ------------------------------------------------- |
62+
| `gcpProject` | `$GOOGLE_CLOUD_PROJECT` | GCP project ID |
63+
| `gcpRegion` | `us-central1` | Cloud Run region |
64+
| `gcpStorageType` | `gcs-fuse` | Storage backend (see above) |
65+
| `gcpBucket` | — | GCS bucket name (for `gcs-fuse`, `gcs-copy`) |
66+
| `gcpFilestoreIp` | — | Filestore IP address (for `nfs`) |
67+
| `gcpFilestoreShare`| `/share1` | Filestore share name (for `nfs`) |
68+
| `gcpMachineType` | `e2-standard-4` | Machine type |
69+
| `gcpDiskSizeGb` | `100` | In-memory volume size (for `in-memory`, max 32) |
70+
| `gcpServiceAccount`| — | Service account email |
71+
| `gcpVpcConnector` | — | VPC connector (required for `nfs`) |
72+
73+
## Examples
74+
75+
### GCS FUSE — mount bucket as filesystem
76+
77+
```yaml
78+
- uses: game-ci/unity-builder@v4
79+
with:
80+
providerStrategy: gcp-cloud-run
81+
gcpProject: my-project
82+
gcpBucket: my-unity-builds
83+
targetPlatform: StandaloneLinux64
84+
```
85+
86+
### NFS — Filestore for fast Library caching
87+
88+
```yaml
89+
- uses: game-ci/unity-builder@v4
90+
with:
91+
providerStrategy: gcp-cloud-run
92+
gcpProject: my-project
93+
gcpStorageType: nfs
94+
gcpFilestoreIp: 10.0.0.2
95+
gcpFilestoreShare: /share1
96+
gcpVpcConnector: my-connector
97+
targetPlatform: StandaloneLinux64
98+
```
99+
100+
### Copy — simple artifact upload/download
101+
102+
```yaml
103+
- uses: game-ci/unity-builder@v4
104+
with:
105+
providerStrategy: gcp-cloud-run
106+
gcpProject: my-project
107+
gcpStorageType: gcs-copy
108+
gcpBucket: my-unity-builds
109+
targetPlatform: StandaloneLinux64
110+
```
111+
112+
## Related
113+
114+
- [Azure ACI](azure-aci) — Azure Container Instances provider
115+
- [Custom Providers](custom-providers) — TypeScript provider plugins
116+
- [CLI Provider Protocol](cli-provider-protocol) — Write providers in any language

‎docs/03-github-orchestrator/05-providers/11-azure-aci.mdx‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Azure ACI (Experimental)
2+
3+
Run Unity builds as [Azure Container Instances](https://learn.microsoft.com/en-us/azure/container-instances/) —
4+
serverless containers with configurable storage backends.
5+
6+
:::caution Experimental
7+
This provider is experimental. APIs and behavior may change between releases.
8+
:::
9+
10+
```
11+
GitHub Actions Runner
12+
┌──────────────────────────┐
13+
│ unity-builder │
14+
│ providerStrategy: │ Azure CLI
15+
│ azure-aci │────────────────► Container Instances API
16+
│ │ ┌─────────────────┐
17+
│ azureStorageType: │ │ Container: │
18+
│ azure-files / │ │ unity-build │
19+
│ blob-copy / │ │ │
20+
│ azure-files-nfs / │ │ Image: unityci │
21+
│ in-memory │ │ Storage: ... │
22+
└──────────────────────────┘ └─────────────────┘
23+
```
24+
25+
## Prerequisites
26+
27+
- Azure CLI installed and authenticated (`az login` or service principal)
28+
- A resource group (auto-created if it doesn't exist)
29+
- **Contributor** role on the resource group
30+
31+
## Storage Types
32+
33+
Set `azureStorageType` to control how the build accesses large files.
34+
35+
| Type | How it works | Best for | Size limit |
36+
| ----------------- | --------------------------------------------------- | --------------------------------- | ----------------- |
37+
| `azure-files` | Mounts an Azure File Share via SMB | General artifact storage | 100 TiB |
38+
| `blob-copy` | Copies artifacts in/out via `az storage blob` | Simple upload/download | Unlimited |
39+
| `azure-files-nfs` | Mounts an Azure File Share via NFS 4.1 | Unity Library (small random reads)| 100 TiB |
40+
| `in-memory` | emptyDir volume (tmpfs) | Scratch/temp during builds | Container memory |
41+
42+
### When to use each type
43+
44+
- **azure-files** (default) — Simplest persistent option. Works out of the box — auto-creates the
45+
storage account and file share if they don't exist. SMB has some overhead from opportunistic
46+
locking but is reliable for most use cases.
47+
48+
- **blob-copy** — Avoids mount overhead entirely. Copies everything before the build starts and
49+
uploads after it finishes. Good when you only need artifact upload/download.
50+
51+
- **azure-files-nfs** — Eliminates SMB lock overhead for better random I/O performance with Unity
52+
Library files (thousands of small files). Requires **Premium FileStorage** (auto-created) and
53+
**VNet integration** via `azureSubnetId`.
54+
55+
- **in-memory** — Fastest option (RAM-backed). Data is lost when the container stops. Size is limited
56+
by the container's memory allocation. Use for temporary build artifacts.
57+
58+
## Inputs
59+
60+
| Input | Default | Description |
61+
| --------------------- | ----------------------- | ------------------------------------------------- |
62+
| `azureResourceGroup` | `$AZURE_RESOURCE_GROUP` | Resource group name |
63+
| `azureLocation` | `eastus` | Azure region |
64+
| `azureStorageType` | `azure-files` | Storage backend (see above) |
65+
| `azureStorageAccount` | `$AZURE_STORAGE_ACCOUNT`| Storage account name |
66+
| `azureBlobContainer` | `unity-builds` | Blob container (for `blob-copy`) |
67+
| `azureFileShareName` | `unity-builds` | File share name (for `azure-files`, `azure-files-nfs`) |
68+
| `azureSubscriptionId` | `$AZURE_SUBSCRIPTION_ID`| Subscription ID |
69+
| `azureCpu` | `4` | CPU cores (1–16) |
70+
| `azureMemoryGb` | `16` | Memory in GB (1–16) |
71+
| `azureDiskSizeGb` | `100` | File share quota in GB |
72+
| `azureSubnetId` | — | Subnet ID for VNet (required for `azure-files-nfs`) |
73+
74+
## Examples
75+
76+
### Azure Files — SMB mount (default)
77+
78+
```yaml
79+
- uses: game-ci/unity-builder@v4
80+
with:
81+
providerStrategy: azure-aci
82+
azureResourceGroup: my-rg
83+
azureStorageAccount: myunitybuilds
84+
targetPlatform: StandaloneLinux64
85+
```
86+
87+
### NFS — better POSIX performance
88+
89+
```yaml
90+
- uses: game-ci/unity-builder@v4
91+
with:
92+
providerStrategy: azure-aci
93+
azureResourceGroup: my-rg
94+
azureStorageType: azure-files-nfs
95+
azureStorageAccount: myunitybuilds
96+
azureSubnetId: /subscriptions/.../subnets/default
97+
targetPlatform: StandaloneLinux64
98+
```
99+
100+
### Blob copy — simple artifact upload/download
101+
102+
```yaml
103+
- uses: game-ci/unity-builder@v4
104+
with:
105+
providerStrategy: azure-aci
106+
azureResourceGroup: my-rg
107+
azureStorageType: blob-copy
108+
azureStorageAccount: myunitybuilds
109+
azureBlobContainer: my-builds
110+
targetPlatform: StandaloneLinux64
111+
```
112+
113+
## Related
114+
115+
- [GCP Cloud Run](gcp-cloud-run) — Google Cloud Run Jobs provider
116+
- [Custom Providers](custom-providers) — TypeScript provider plugins
117+
- [CLI Provider Protocol](cli-provider-protocol) — Write providers in any language

0 commit comments

Comments
 (0)