Retained Workspaces

Retained workspaces cache the entire project folder between builds. This provides the fastest possible rebuilds at the cost of more cloud storage.

Configuration

Set maxRetainedWorkspaces to control how many workspaces are kept:

Value	Behavior
0	Unlimited retained workspaces (default).
> 0	Keep at most N workspaces. Additional jobs fall back to standard caching.

Each retained workspace is locked during use — only one build can use a workspace at a time. Orchestrator handles locking automatically via S3 or rclone. See Caching for storage provider details.

  maxRetainedWorkspaces: 3

  Workspace 1         Workspace 2         Workspace 3
 ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
 │ [locked]      │   │ [locked]      │   │ (idle)        │
 │ Build A       │   │ Build B       │   │               │
 │ Full project  │   │ Full project  │   │ Full project  │
 └───────────────┘   └───────────────┘   └───────────────┘

  Build C arrives --> claims Workspace 3
  Build D arrives --> all locked --> falls back to standard caching

Example

- uses: game-ci/unity-builder@v4
  with:
    providerStrategy: aws
    maxRetainedWorkspaces: 3
    targetPlatform: StandaloneLinux64
    gitPrivateToken: ${{ secrets.GITHUB_TOKEN }}

⚠️ Storage Considerations

Each retained workspace stores a full copy of your project. For a 20 GB project with 3 retained workspaces, expect ~60 GB of cloud storage usage.