Caching

Orchestrator supports two caching strategies. You can mix both by setting maxRetainedWorkspaces — once the limit is reached, additional jobs fall back to standard caching.

  Standard Caching                Retained Workspace
 ┌─────────────────┐             ┌─────────────────┐
 │ LFS files       │             │ Entire project   │
 │ Library/        │             │ folder           │
 │                 │             │                  │
 │ Smaller storage │             │ Faster builds    │
 │ Good for small  │             │ Good for large   │
 │ projects        │             │ projects         │
 └─────────────────┘             └─────────────────┘

Standard Caching

Caches only the Unity Library folder and LFS files between builds. Uses less storage but requires re-importing unchanged assets.

• ✅ Minimum storage cost
• ✅ Best for smaller projects
• ⚠️ Slower rebuilds for large asset libraries

Build Caching

Orchestrator automatically caches build output alongside the Library cache. After each build, the compiled output folder is archived and stored using the same cache key (branch name by default). On the next build with the same cache key, the previous build output is available at /data/cache/{cacheKey}/build/.

This happens automatically — no configuration required. The cache key controls which builds share output:

# Builds on the same branch share cached output (default behavior)
cacheKey: ${{ github.ref_name }}

# Or share across branches by using a fixed key
cacheKey: shared-cache

Build caching uses the same compression and storage provider as Library caching. Archives are stored as build-{buildGuid}.tar.lz4 (or .tar if compression is disabled). See Storage for details on compression and storage backends.

Retained Workspace

Caches the entire project folder between builds. Provides the fastest rebuilds but consumes more storage.

• ✅ Maximum build speed
• ✅ Best for large projects with long import times
• ⚠️ Higher storage cost

See Retained Workspaces for configuration details.

🗄️ Storage Providers

Provider	storageProvider	Description
S3	s3 (default)	AWS S3 storage. Works with both AWS and LocalStack.
Rclone	rclone	Flexible cloud storage via rclone. Supports 70+ backends (Google Cloud, Azure Blob, Backblaze, SFTP, etc).

Configure with the storageProvider parameter. When using rclone, also set rcloneRemote to your configured remote endpoint.

🔒 Workspace Locking

When using retained workspaces, Orchestrator uses distributed locking (via S3 or rclone) to ensure only one build uses a workspace at a time. This enables safe concurrent builds that share and reuse workspaces without conflicts.

Locking is managed automatically — no configuration required beyond setting maxRetainedWorkspaces.