game-ci/Unity - Orchestrator

Build Unity projects with orchestrator features: remote providers (AWS, K8s, GCP, Azure), hot runner, test workflows, local caching, child workspaces, artifact management, and more. Wraps game-ci/unity-builder and adds orchestrator-specific configuration.

View on GitHub

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Activelast commit May 22, 2026
License: MIT

Pinned Snippet

workflow.ymlSHA-pinned

uses: game-ci/orchestrator@68bbf9987faf5a6f19cbc9b157004cd320f6a92e # v1.0.0

tags can be moved; commit SHAs can't. why a SHA?

Inputs

name	description	required	default
targetPlatform	Platform that the build should target.	yes	""
unityVersion	Unity version. Use "auto" to detect from ProjectSettings/ProjectVersion.txt	no	auto
customImage	Specific docker image for building the project	no	""
projectPath	Path to the project, relative to repo root.	no	""
buildProfile	Path to the build profile to activate, relative to the project root.	no	""
buildName	Name of the build (no file extension).	no	""
buildsPath	Path where builds should be stored.	no	""
buildMethod	Namespace.Class.StaticMethod to perform the build.	no	""
manualExit	Suppress -quit flag.	no	""
enableGpu	Launch unity without -nographics.	no	""
customParameters	Custom parameters to configure the build.	no	""
versioning	Versioning scheme.	no	Semantic
version	Version for "Custom" versioning scheme.	no	""
androidVersionCode	—	no	""
androidExportType	—	no	androidPackage
androidKeystoreName	—	no	""
androidKeystoreBase64	—	no	""
androidKeystorePass	—	no	""
androidKeyaliasName	—	no	""
androidKeyaliasPass	—	no	""
androidTargetSdkVersion	—	no	""
androidSymbolType	—	no	none
sshAgent	—	no	""
sshPublicKeysDirectoryPath	—	no	""
gitPrivateToken	GitHub private token for git operations	no	""
runAsHostUser	—	no	false
chownFilesTo	—	no	""
dockerCpuLimit	—	no	""
dockerMemoryLimit	—	no	""
dockerIsolationMode	—	no	default
containerRegistryRepository	—	no	unityci/editor
containerRegistryImageVersion	—	no	3
allowDirtyBuild	—	no	""
cacheUnityInstallationOnMac	—	no	false
unityHubVersionOnMac	—	no	""
unityLicensingServer	—	no	""
dockerWorkspacePath	—	no	/github/workspace
skipActivation	—	no	false
providerStrategy	Build provider: local, aws, k8s, gcp-cloud-run, azure-aci, github-actions, gitlab-ci, ansible, remote-powershell, or a custom provider path/URL.	no	local
fallbackProviderStrategy	Fallback provider when the primary is unavailable.	no	""
runnerCheckEnabled	Check runner availability before starting a build.	no	false
runnerCheckLabels	Comma-separated runner labels to filter when checking availability.	no	""
runnerCheckMinAvailable	Minimum idle runners required for primary provider.	no	1
retryOnFallback	Retry on fallback provider if primary fails.	no	false
providerInitTimeout	Max seconds to wait for provider initialization. 0 = no timeout.	no	0
providerExecutable	Path to an external CLI executable that implements the provider protocol.	no	""
containerCpu	CPU units for the remote build container.	no	1024
containerMemory	Memory (MB) for the remote build container.	no	3072
containerNamespace	—	no	default
awsStackName	CloudFormation stack name for AWS provider.	no	game-ci
kubeConfig	Base64-encoded kubeconfig for K8s provider.	no	""
kubeVolume	—	no	""
kubeVolumeSize	—	no	25Gi
kubeStorageClass	—	no	""
gcpProject	Google Cloud project ID.	no	""
gcpRegion	—	no	""
gcpStorageType	Storage type: gcs-fuse, gcs-copy, nfs, in-memory.	no	gcs-fuse
gcpBucket	—	no	""
gcpFilestoreIp	—	no	""
gcpFilestoreShare	—	no	/share1
gcpMachineType	—	no	e2-standard-4
gcpDiskSizeGb	—	no	100
gcpServiceAccount	—	no	""
gcpVpcConnector	—	no	""
azureResourceGroup	—	no	""
azureLocation	—	no	""
azureStorageType	—	no	azure-files
azureStorageAccount	—	no	""
azureBlobContainer	—	no	unity-builds
azureFileShareName	—	no	unity-builds
azureSubscriptionId	—	no	""
azureCpu	—	no	4
azureMemoryGb	—	no	16
azureDiskSizeGb	—	no	100
azureSubnetId	—	no	""
remotePowershellHost	—	no	""
remotePowershellCredential	—	no	""
remotePowershellTransport	—	no	wsman
githubActionsRepo	—	no	""
githubActionsWorkflow	—	no	""
githubActionsToken	—	no	""
githubActionsRef	—	no	main
gitlabProjectId	—	no	""
gitlabTriggerToken	—	no	""
gitlabApiUrl	—	no	https://gitlab.com
gitlabRef	—	no	main
ansibleInventory	—	no	""
ansiblePlaybook	—	no	""
ansibleExtraVars	—	no	""
ansibleVaultPassword	—	no	""
gitAuthMode	Git auth mode: header (default) or url.	no	header
gitIntegrityCheck	Run git fsck, lock cleanup, and submodule validation before build.	no	false
gitAutoRecover	—	no	false
cleanReservedFilenames	—	no	false
unityProcessCleanup	On Windows self-hosted runners, clean stale Unity processes scoped to the project path before launch.	no	false
enableBuildDiagnostics	Analyze Unity Editor log after build/test and emit categorized failure summary to console and GitHub Step Summary.	no	true
enableUnityRetry	Enable multi-phase Unity retry with automatic recovery actions based on failure category.	no	false
unityRetryMaxAttempts	Maximum number of Unity retry attempts (including the initial run).	no	3
licensingStaggerDelay	Apply hash-based stagger delay before Unity launch to avoid licensing IPC mutex contention on self-hosted runners.	no	true
profileFingerprintEnabled	Detect submodule profile changes and clear stale ScriptAssemblies/Bee when the profile fingerprint differs from cache.	no	false
workerCount	Set -job-worker-count for Unity launch. 0 means use Unity default. Controls import parallelism.	no	0
ilppCleanupEnabled	Clean up crashed ILPP processes scoped to the workspace before Unity launch (Windows only).	no	true
acceleratorMode	Unity Accelerator mode: enabled (full), disabled (off), or download-only (pull but no upload).	no	enabled
testResultCleanup	Delete stale test result XML files before test runner launch to prevent false positives.	no	true
disableAssemblyUpdater	Add -disable-assembly-updater to batchmode launches to prevent ApiUpdater from destabilizing CI sessions.	no	true
collectUnityLogs	Collect Unity-internal logs (Editor.log, Unity.Licensing.Client.log, Unity.Entitlements.Audit.log, services-config.json, Unity Hub logs, crash dumps, build report, bee_backend.log, IL2CPP output, project version, package manifest, etc.) into <workspace>/Logs/UnityDiagnostics/ after the build so they can be uploaded as artifacts and shared with Unity support. See also: collectUnityLogsOnSuccess, unityLogCategories.	no	false
collectUnityLogsOnSuccess	When false, only collect Unity logs on non-zero exit codes. Default true so successful builds also publish diagnostic artifacts (useful for licensing audits and Unity support tickets).	no	true
unityLogCategories	Comma-separated subset of categories to collect (default = all non-sensitive). Categories: editor-log, editor-prev-log, licensing-client, entitlements-audit, services-config, unity-hub-info, unity-hub-error, editor-crash, build-report, bee-backend, player-log, test-results, il2cpp-output, project-version, package-manifest, macos-crash-report, windows-event-log.	no	""
unityLogsIncludeSensitive	Include sensitive categories (e.g. license-file). NEVER enable in public CI artifacts. Off by default.	no	false
unityLogsOutputDir	Override the output directory for collected Unity logs. Default is <workspace>/Logs/UnityDiagnostics/.	no	""
streamUnityLogs	Live-tail Unity log files during the build and forward each new line to the GitHub Actions log. Useful for long builds where you want to see compile/import progress without waiting for the build to finish.	no	false
streamUnityLogPaths	Comma-separated list of files to live-tail. Defaults to the standard <project>/Builds/Logs/Editor.log path that unity-builder configures.	no	""
buildArchiveEnabled	—	no	false
buildArchivePath	—	no	./build-archives
buildArchiveRetention	—	no	30
submoduleProfilePath	Path to YAML submodule profile file.	no	""
submoduleVariantPath	—	no	""
submoduleToken	—	no	""
localCacheEnabled	Enable filesystem-based caching for local builds.	no	false
localCacheRoot	—	no	""
localCacheLibrary	—	no	true
localCacheLfs	—	no	false
localCacheFallback	When the exact local cache key misses, try compatible cache keys from the same platform/version.	no	false
localCacheFallbackKeys	Comma-separated explicit local cache fallback keys to try after the exact key.	no	""
localCacheMode	Local Library cache mode: tar, copy-directory, move-directory, or canonical-overlay. move-directory is intended for same-volume Windows self-hosted runners. canonical-overlay (opt-in, NTFS/ext4/xfs) writes the cache once to a canonical store and per-runner overlays consume it via OS-native hardlinks. Falls back to move-directory on filesystems without hardlink support.	no	tar
canonicalCacheRoot	Path for the canonical cache store when localCacheMode=canonical-overlay. Falls back to <localCacheRoot>/canonical when unset.	no	""
canonicalCacheClassifier	JSON describing per-subdirectory hardlink/junction/copy/skip strategy. Default targets Unity Library structure (PackageCache=junction, ScriptAssemblies/Artifacts/etc.=hardlink, PackageManager+DAG companions=copy, editor session state=skip). Override for non-Unity engines or non-default Library layouts.	no	""
canonicalCacheVersionRetention	How many canonical SHA versions to keep per cache key. Older versions are pruned by mtime.	no	2
cacheMaterialize	Materialization timing for canonical-overlay: eager (always live materialize before build) or prepared (build a per-runner overlay during PostUnityJob, atomic-rename into place during next PreUnityJob for sub-second hydration).	no	eager
cacheSentinelCanary	Defense-in-depth corruption check. Writes a canary file with known content into the overlay at materialize; verifies on consume. Catches silent corruption on aging hardware. Off by default.	no	false
upmOfflineEnabled	When UPM fingerprint matches cached state, set UPM_OFFLINE=1 to skip network package resolution.	no	false
backgroundCacheSave	Save cache directory copies in a detached background process to avoid blocking the pipeline.	no	false
childWorkspacesEnabled	Enable child workspace isolation for multi-product builds.	no	false
childWorkspaceName	—	no	""
childWorkspaceCacheRoot	—	no	""
childWorkspacePreserveGit	—	no	true
childWorkspaceSeparateLibrary	—	no	true
lfsTransferAgent	Custom Git LFS transfer agent.	no	""
lfsTransferAgentArgs	—	no	""
lfsStoragePaths	—	no	""
gitHooksEnabled	—	no	false
gitHooksSkipList	—	no	""
gitHooksRunBeforeBuild	—	no	""
hotRunnerEnabled	Use persistent hot runner for builds.	no	false
hotRunnerTransport	—	no	websocket
hotRunnerHost	—	no	localhost
hotRunnerPort	—	no	9090
hotRunnerHealthInterval	—	no	30
hotRunnerMaxIdle	—	no	3600
hotRunnerFallbackToCold	—	no	true
artifactOutputTypes	Comma-separated output types to collect.	no	build,logs,test-results
artifactUploadTarget	Upload destination: github-artifacts, storage, local, none.	no	github-artifacts
artifactUploadPath	—	no	""
artifactCompression	—	no	gzip
artifactRetentionDays	—	no	30
artifactCustomTypes	—	no	""
preflightSuite	Path to YAML preflight suite definition file. Preflight runs fast, no-engine validation checks before the build dispatch and fails fast on the first failure. Set to "default" to run the built-in fallback suite when no .game-ci/preflight-suite.yml exists. Empty disables preflight entirely.	no	""
testSuitePath	Path to YAML test suite definition file.	no	""
testSuiteEvent	—	no	""
testFilterRefs	Comma-separated suite filter preset names to inject into every test run.	no	""
testFilterInjection	Inline YAML or JSON filter overlay injected into every test run. Supports refs, filters, and filterSets.	no	""
testFilterInjectionPath	Path to a YAML or JSON test filter overlay file injected into every test run.	no	""
testTaxonomyPath	—	no	""
testResultFormat	—	no	junit
testResultPath	—	no	./test-results
syncStrategy	Workspace sync strategy: full, git-delta, direct-input, storage-pull.	no	full
syncInputRef	—	no	""
syncStorageRemote	—	no	""
syncRevertAfter	—	no	true
syncStatePath	—	no	.game-ci/sync-state.json
orchestratorRepoName	—	no	game-ci/unity-builder
cloneDepth	—	no	50
secretSource	Secret source for pulling build secrets.	no	""
storageProvider	—	no	s3
rcloneRemote	—	no	""
cacheKey	—	no	""
skipLfs	—	no	false
skipCache	—	no	false
skipInContainerClone	When true, skip the in-container git clone and reuse a pre-hydrated workspace bind-mounted by the caller. The caller must ensure the repository (with .git/, submodules, and LFS objects hydrated as needed) is present at the orchestrator workspace path before the container starts. Intended for self-hosted runners that use private LFS backends or other host-side credentials/config that cannot be replicated inside the container.	no	false
repoPathOverride	Override the in-container repository path used by the orchestrator. When set, OrchestratorFolders.repoPathAbsolute returns this value instead of the default ${uniqueOrchestratorJobFolderAbsolute}/${repositoryFolder} layout. Intended to be paired with skipInContainerClone so the caller can point the orchestrator at a pre-hydrated workspace already bind-mounted at a fixed container path (for example /data, which is the default local-docker bind-mount target). Empty string preserves the default path. Setting this without skipInContainerClone is rejected at bootstrap because it would only affect the repo path and not the surrounding cache/builder paths, producing a divergent layout.	no	""
maxCacheEntries	Max cache tar entries to retain per folder	no	2
minCacheEntries	Minimum cache entries to keep during age-based GC (floor)	no	0
gcTimeoutMinutes	Force garbage collection after this many minutes (0 = disabled)	no	0
configFiles	JSON map of filename to content to inject into container workspace	no	{}
postBuildSteps	—	no	""
preBuildSteps	—	no	""
containerHookFiles	—	no	""
customHookFiles	—	no	""
customCommandHooks	—	no	""
customJob	—	no	""
commandHooks	—	no	""

Outputs

name	description
volume	The Persistent Volume where build artifacts are stored (K8s)
buildVersion	The generated version used for the Unity build
androidVersionCode	The generated versionCode for Android builds
engineExitCode	Exit code from the build (0 = success)
artifactManifestPath	Path to the generated artifact manifest JSON