unity-builder/action.yml

name: 'Unity - Builder'
author: Webber Takken <webber@takken.io>
description: 'Build Unity projects for different platforms.'
inputs:
  targetPlatform:
    required: true
    default: ''
    description: 'Platform that the build should target.'
  unityVersion:
    required: false
    default: 'auto'
    description:
      'Version of unity to use for building the project. Use "auto" to get from your ProjectSettings/ProjectVersion.txt'
  customImage:
    required: false
    default: ''
    description: 'Specific docker image that should be used for building the project'
  projectPath:
    required: false
    default: ''
    description: 'Path to the project to be built, relative to the repository root.'
  buildProfile:
    required: false
    default: ''
    description: 'Path to the build profile to activate, relative to the project root.'
  buildName:
    required: false
    default: ''
    description: 'Name of the build. Should not include a file extension.'
  buildsPath:
    required: false
    default: ''
    description: 'Path where the builds should be stored.'
  buildMethod:
    required: false
    default: ''
    description: 'Path to a Namespace.Class.StaticMethod to run to perform the build.'
  manualExit:
    required: false
    default: ''
    description: 'Suppresses `-quit`. Exit your build method using `EditorApplication.Exit(0)` instead.'
  enableGpu:
    required: false
    default: ''
    description: 'Launches unity without specifying `-nographics`.'
  customParameters:
    required: false
    default: ''
    description: 'Custom parameters to configure the build.'
  versioning:
    required: false
    default: 'Semantic'
    description: 'The versioning scheme to use when building the project'
  version:
    required: false
    default: ''
    description: 'The version, when used with the "Custom" versioning scheme'
  androidVersionCode:
    required: false
    default: ''
    description: 'The android versionCode'
  androidExportType:
    required: false
    default: 'androidPackage'
    description:
      'The android export type. Should be androidPackage for apk, androidAppBundle for aab, or androidStudioProject for
      an android studio project.'
  androidKeystoreName:
    required: false
    default: ''
    description: 'The android keystoreName'
  androidKeystoreBase64:
    required: false
    default: ''
    description: 'The base64 contents of the android keystore file'
  androidKeystorePass:
    required: false
    default: ''
    description: 'The android keystorePass'
  androidKeyaliasName:
    required: false
    default: ''
    description: 'The android keyaliasName'
  androidKeyaliasPass:
    required: false
    default: ''
    description: 'The android keyaliasPass'
  androidTargetSdkVersion:
    required: false
    default: ''
    description: 'The android target API level.'
  androidSymbolType:
    required: false
    default: 'none'
    description: 'The android symbol type to export. Should be "none", "public" or "debugging".'
  sshAgent:
    required: false
    default: ''
    description: 'SSH Agent path to forward to the container'
  sshPublicKeysDirectoryPath:
    required: false
    default: ''
    description: 'Path to a directory containing SSH public keys to forward to the container.'
  gitPrivateToken:
    required: false
    default: ''
    description: '[Orchestrator] Github private token to pull from github'
  gitAuthMode:
    required: false
    default: 'header'
    description:
      '[Orchestrator] How git authentication is configured. "header" (default) uses http.extraHeader so the token
      never appears in clone URLs or git config. "url" embeds the token in clone URLs (legacy behavior).'
  githubOwner:
    required: false
    default: ''
    description: '[Orchestrator] GitHub owner name or organization/team name'
  runAsHostUser:
    required: false
    default: 'false'
    description:
      'Whether to run as a user that matches the host system or the default root container user. Only applicable to
      Linux hosts and containers. This is useful for fixing permission errors on Self-Hosted runners.'
  chownFilesTo:
    required: false
    default: ''
    description:
      'User and optionally group (user or user:group or uid:gid) to give ownership of the resulting build artifacts'
  dockerCpuLimit:
    required: false
    default: ''
    description: 'Number of CPU cores to assign the docker container. Defaults to all available cores on all platforms.'
  dockerMemoryLimit:
    required: false
    default: ''
    description:
      'Amount of memory to assign the docker container. Defaults to 95% of total system memory rounded down to the
      nearest megabyte on Linux and 80% on Windows. On unrecognized platforms, defaults to 75% of total system memory.
      To manually specify a value, use the format <number><unit>, where unit is either m or g. ie: 512m = 512 megabytes'
  dockerIsolationMode:
    required: false
    default: 'default'
    description:
      'Isolation mode to use for the docker container. Can be one of process, hyperv, or default. Default will pick the
      default mode as described by Microsoft where server versions use process and desktop versions use hyperv. Only
      applicable on Windows'
  containerRegistryRepository:
    required: false
    default: 'unityci/editor'
    description: 'Container registry and repository to pull image from. Only applicable if customImage is not set.'
  containerRegistryImageVersion:
    required: false
    default: '3'
    description: 'Container registry image version. Only applicable if customImage is not set.'
  allowDirtyBuild:
    required: false
    default: ''
    description: '[Orchestrator] Allows the branch of the build to be dirty, and still generate the build.'
  postBuildSteps:
    required: false
    default: ''
    description:
      '[Orchestrator] run a post build job in yaml format with the keys image, secrets (name, value object array),
      command string'
  preBuildSteps:
    required: false
    default: ''
    description:
      '[Orchestrator] Run a pre build job after the repository setup but before the build job (in yaml format with the
      keys image, secrets (name, value object array), command line string)'
  containerHookFiles:
    required: false
    default: ''
    description:
      '[Orchestrator] Specify the names (by file name) of custom steps to run before or after orchestrator jobs, must
      match a yaml step file inside your repo in the folder .game-ci/steps/'
  customHookFiles:
    required: false
    default: ''
    description:
      '[Orchestrator] Specify the names (by file name) of custom hooks to run before or after orchestrator jobs, must
      match a yaml step file inside your repo in the folder .game-ci/hooks/'
  customCommandHooks:
    required: false
    default: ''
    description: '[Orchestrator] Specify custom commands and trigger hooks (injects commands into jobs)'
  customJob:
    required: false
    default: ''
    description:
      '[Orchestrator] Run a custom job instead of the standard build automation for orchestrator (in yaml format with
      the keys image, secrets (name, value object array), command line string)'
  awsStackName:
    default: 'game-ci'
    required: false
    description: '[Orchestrator] The Cloud Formation stack name that must be setup before using this option.'
  providerStrategy:
    default: 'local'
    required: false
    description:
      '[Orchestrator] Either local, k8s or aws can be used to run builds on a remote cluster. Additional parameters must
      be configured.'
  resourceTracking:
    default: 'false'
    required: false
    description: '[Orchestrator] Enable resource tracking logs for disk usage and allocation summaries.'
  containerCpu:
    default: ''
    required: false
    description: '[Orchestrator] Amount of CPU time to assign the remote build container'
  containerMemory:
    default: ''
    required: false
    description: '[Orchestrator] Amount of memory to assign the remote build container'
  readInputFromOverrideList:
    default: ''
    required: false
    description: '[Orchestrator] Comma separated list of input value names to read from "input override command"'
  readInputOverrideCommand:
    default: ''
    required: false
    description:
      '[Orchestrator] Extend game ci by specifying a command to execute to pull input from external source e.g cloud
      provider secret managers'
  kubeConfig:
    default: ''
    required: false
    description:
      '[Orchestrator] Supply a base64 encoded kubernetes config to run builds on kubernetes and stream logs until
      completion.'
  kubeVolume:
    default: ''
    required: false
    description: '[Orchestrator] Supply a Persistent Volume Claim name to use for the Unity build.'
  kubeStorageClass:
    default: ''
    required: false
    description:
      '[Orchestrator] Kubernetes storage class to use for orchestrator jobs, leave empty to install rook cluster.'
  kubeVolumeSize:
    default: '5Gi'
    required: false
    description: '[Orchestrator] Amount of disc space to assign the Kubernetes Persistent Volume'
  cacheKey:
    default: ''
    required: false
    description: '[Orchestrator] Cache key to indicate bucket for cache'
  watchToEnd:
    default: 'true'
    required: false
    description:
      '[Orchestrator] Whether or not to watch the build to the end. Can be used for especially long running jobs e.g
      imports or self-hosted ephemeral runners.'
  cacheUnityInstallationOnMac:
    default: 'false'
    required: false
    description: 'Whether to cache the Unity hub and editor installation on MacOS'
  unityHubVersionOnMac:
    default: ''
    required: false
    description:
      'The version of Unity Hub to install on MacOS (e.g. 3.4.0). Defaults to latest available on brew if empty string
      or nothing is specified.'
  unityLicensingServer:
    default: ''
    required: false
    description: 'The Unity licensing server address to use for activating Unity.'
  dockerWorkspacePath:
    default: '/github/workspace'
    required: false
    description:
      'The path to mount the workspace inside the docker container. For windows, leave out the drive letter. For example
      c:/github/workspace should be defined as /github/workspace'
  skipActivation:
    default: 'false'
    required: false
    description: 'Skip the activation/deactivation of Unity. This assumes Unity is already activated.'
  cloneDepth:
    default: '50'
    required: false
    description: '[Orchestrator] Specifies the depth of the git clone for the repository. Use 0 for full clone.'
  orchestratorRepoName:
    default: 'game-ci/unity-builder'
    required: false
    description:
      '[Orchestrator] Specifies the repo for the unity builder. Useful if you forked the repo for testing, features, or
      fixes.'
  submoduleProfilePath:
    required: false
    default: ''
    description:
      'Path to a YAML submodule profile file (relative to repo root). Defines which submodules to initialize (branch:
      main) or skip (branch: empty). See docs for format.'
  submoduleVariantPath:
    required: false
    default: ''
    description:
      'Path to a YAML variant overlay file that modifies the base submodule profile. Used for server or debug build
      variants.'
  submoduleToken:
    required: false
    default: ''
    description:
      'Git token for authenticating submodule clones. Falls back to gitPrivateToken or GITHUB_TOKEN if empty.'
  localCacheEnabled:
    required: false
    default: 'false'
    description:
      'Enable filesystem-based caching for local builds. Caches the Unity Library folder and optionally LFS objects
      between builds without requiring actions/cache.'
  localCacheRoot:
    required: false
    default: ''
    description:
      'Root directory for local build cache. Defaults to $RUNNER_TEMP/game-ci-cache or .game-ci/cache if RUNNER_TEMP is
      not set.'
  localCacheLibrary:
    required: false
    default: 'true'
    description: 'Cache the Unity Library folder for local builds. Only effective when localCacheEnabled is true.'
  localCacheLfs:
    required: false
    default: 'false'
    description: 'Cache Git LFS objects for local builds. Only effective when localCacheEnabled is true.'
  childWorkspacesEnabled:
    required: false
    default: 'false'
    description:
      'Enable child workspace isolation for multi-product builds. Uses atomic filesystem moves for O(1) workspace
      restore instead of tar/download/extract. Ideal for 50GB+ workspaces on self-hosted runners.'
  childWorkspaceName:
    required: false
    default: ''
    description:
      'Name for this child workspace (e.g., product name like "TurnOfWar"). Used as the cache key for workspace
      isolation. Required when childWorkspacesEnabled is true.'
  childWorkspaceCacheRoot:
    required: false
    default: ''
    description:
      'Parent directory for cached child workspaces. Should be on the same NTFS volume as the build directory for O(1)
      atomic restore via filesystem rename. Defaults to $RUNNER_TEMP/game-ci-workspaces.'
  childWorkspacePreserveGit:
    required: false
    default: 'true'
    description:
      'Preserve .git directory in cached child workspace. Enables delta operations on restore but increases cache size.
      Set to false to save disk space at the cost of full re-clone on restore.'
  childWorkspaceSeparateLibrary:
    required: false
    default: 'true'
    description:
      'Cache Unity Library folder separately from the child workspace. Allows independent Library restore even when
      workspace cache is invalidated. Recommended for large projects.'
  lfsTransferAgent:
    required: false
    default: ''
    description:
      'Custom Git LFS transfer agent. Set to "elastic-git-storage" for built-in support (auto-installs from GitHub
      releases). Append @version for a specific release (e.g. "elastic-git-storage@v1.0.0"). Or provide a path to any
      custom transfer agent executable. When set, the agent is registered via git config before LFS operations.'
  lfsTransferAgentArgs:
    required: false
    default: ''
    description: 'Additional arguments to pass to the custom LFS transfer agent.'
  lfsStoragePaths:
    required: false
    default: ''
    description:
      'Semicolon-separated list of storage paths for the custom LFS transfer agent. Interpretation depends on the agent
      (e.g. local paths, WebDAV URLs, rclone remotes).'
  gitHooksEnabled:
    required: false
    default: 'false'
    description:
      'Install and run git hooks (lefthook, husky, or native) during builds. When false (default), hooks are disabled
      for build performance.'
  gitHooksSkipList:
    required: false
    default: ''
    description:
      'Comma-separated list of hook names to skip even when gitHooksEnabled is true. Example: pre-push,post-merge'
  gitHooksRunBeforeBuild:
    required: false
    default: ''
    description:
      'Comma-separated list of lefthook hook groups to run before the Unity build. Allows CI to trigger checks that
      normally only run on git events. Example: pre-commit,pre-push. Requires lefthook. Works with Unity Git Hooks
      (com.frostebite.unitygithooks) when installed as a UPM package — the init script runs automatically.'
  providerExecutable:
    required: false
    default: ''
    description:
      'Path to an external CLI executable that implements the provider protocol. Enables providers written in any
      language (Go, Python, Rust, shell). Uses JSON-over-stdin/stdout communication.'
  gitIntegrityCheck:
    description: 'Run git integrity checks before build (fsck, lock cleanup, submodule validation)'
    required: false
    default: 'false'
  gitAutoRecover:
    description: 'Attempt automatic recovery if git corruption is detected'
    required: false
    default: 'false'
  cleanReservedFilenames:
    description: 'Remove Windows reserved filenames that cause Unity import loops'
    required: false
    default: 'false'
  buildArchiveEnabled:
    description: 'Archive build output after successful build'
    required: false
    default: 'false'
  buildArchivePath:
    description: 'Path to store build archives'
    required: false
    default: './build-archives'
  buildArchiveRetention:
    description: 'Days to retain build archives before cleanup'
    required: false
    default: '30'

outputs:
  volume:
    description: 'The Persistent Volume (PV) where the build artifacts have been stored by Kubernetes'
  buildVersion:
    description: 'The generated version used for the Unity build'
  androidVersionCode:
    description: 'The generated versionCode used for the Android Unity build'
  engineExitCode:
    description:
      'Returns the exit code from the build scripts. This code is 0 if the build was successful. If there was an error
      during activation, the code is from the activation step. If activation is successful, the code is from the project
      build step.'
branding:
  icon: 'box'
  color: 'gray-dark'
runs:
  using: 'node20'
  main: 'dist/index.js'