Orchestrated Jobs

Core stays lean — advanced capability lives here

game-ci build, game-ci test, and game-ci activate are deliberately thin, engine-invocation wrappers and stay that way on purpose. Caching, retry/recovery, extensibility hooks, and wrapping the engine's own process launch are orchestrate's job, not core's — see Orchestrate: advanced topics for local caching, middleware/hooks, build retry, and the engine launch wrapper.

game-ci orchestrate schedules a provider-backed engine job. Providers can run standard builds, test workflows, custom engine commands, or a fully custom job definition.

game-ci orchestrate [projectPath] --provider-strategy <strategy>

game-ci remote run and game-ci remote build remain available as compatibility aliases, but new workflows should use game-ci orchestrate so the command name matches the provider-backed job model.

The CLI owns the high-level command shape. Providers own infrastructure-specific options and job execution behavior.

Public CLI vs Standalone Orchestrator

Use game-ci orchestrate from the public CLI for normal provider-backed jobs. It keeps the command model engine-oriented and lets provider plugins add infrastructure details.

The standalone Orchestrator package also installs a game-ci orchestrate command. That command is a direct, lower-level Orchestrator entry point for provider development, debugging, and environments that intentionally run Orchestrator without the public CLI. The verb is the same, but the installed package determines the command surface.

Need	Use
Friendly public CLI command for builds, tests, or jobs	game-ci orchestrate
Backwards-compatible old public CLI command names	game-ci remote run, remote build
Direct standalone Orchestrator provider execution	game-ci orchestrate
Executable provider protocol integration	game-ci serve in the provider tool

Built-In Orchestrator

The Orchestrator is the default provider backend for provider-backed execution, and it ships as a built-in plugin — game-ci registers it automatically, the same way it registers the built-in Unity, Godot, and Unreal engine plugins. You do not need to pass --plugin to use game-ci orchestrate or any --provider-strategy:

game-ci orchestrate ./my-unity-project \
  --provider-strategy local-docker \
  --target-platform StandaloneLinux64

Available Orchestrator provider types include:

Provider type	Strategy value	Description
Local Docker	local-docker	Run the job in Docker on the current machine.
Local System	local, local-system	Run directly on the current machine, no Docker. See Local System below.
AWS	aws	Run on AWS ECS/Fargate.
Kubernetes	k8s	Run as a Kubernetes job.
Google Cloud Run	gcp-cloud-run	Run on Google Cloud Run.
Azure ACI	azure-aci	Run on Azure Container Instances.
GitHub Actions	github-actions	Dispatch to a GitHub Actions workflow.
GitLab CI	gitlab-ci	Trigger a GitLab CI pipeline.
Remote PowerShell	remote-powershell	Run on a remote Windows host.
Ansible	ansible	Run through an Ansible inventory and playbook.
CLI protocol	cli	Delegate to a custom provider executable.
Config-defined	config:<path>	Map lifecycle commands from YAML or JSON.

Local Docker

game-ci orchestrate ./my-unity-project \
  --provider-strategy local-docker \
  --target-platform StandaloneLinux64

Use this when you want Orchestrator behavior, such as provider hooks and workspace services, without starting with a cloud account.

Local System

--provider-strategy local (the alias local-system resolves to the same provider) runs the build directly on this machine — no Docker, no cloud account:

game-ci orchestrate ./my-unity-project \
  --provider-strategy local \
  --target-platform StandaloneLinux64

This drives the host activate → build/test → return-license step-script chain. It is comparable to the public CLI's classic game-ci test --docker --local host path, but is sourced from Orchestrator build parameters. The core game-ci build command uses Docker on Linux and Windows. Unlike local-docker (and the cloud providers above), the local strategy does not clone the repository or pull Git LFS content for you — it assumes the project at the invocation directory is already checked out and hydrated. That's the point of the strategy: it targets a persistent, self-hosted runner where the workspace already exists between runs, rather than a fresh container or VM.

Common Local System options:

Option	Default	Description
--skip-activation	false	Skip the per-run Unity license activation/return steps. For a self-hosted runner with an already-licensed, long-lived Unity Hub session, rather than one that activates and deactivates on every run.
--engine-launch-wrapper	empty	Prefix the engine process with a host command such as flock. See Engine launch wrapper.

The local/local-system strategy is also where the rest of the advanced, self-hosted-runner surface lives:

• Local caching — persist the Unity Library folder and Git LFS objects across runs (--local-cache-enabled and friends).
• Middleware and hooks — run your own commands/containers around pipeline phases (--middleware-pipeline, --middleware-files).
• Build retry and recovery — opt-in classify/decide/retry recovery for known-transient Unity build failures (--enable-build-retry).
• Engine launch wrapper — wrap the engine's own process launch, e.g. with a launch-serialization lock (--engine-launch-wrapper).

AWS

export AWS_PROFILE=my-profile
export AWS_DEFAULT_REGION=us-east-1

game-ci orchestrate ./my-unity-project \
  --provider-strategy aws \
  --target-platform StandaloneLinux64 \
  --container-cpu 2048 \
  --container-memory 8192

Common AWS options:

Option	Default	Description
--region	eu-west-2	Cloud provider region.
--aws-stack-name	game-ci	CloudFormation stack name.
--container-cpu	1024	Container CPU units.
--container-memory	3072	Container memory in MB.
--aws-use-spot	false	Use Spot capacity.
--aws-spot-fallback	true	Fall back to on-demand capacity.
--aws-use-ephemeral-storage	false	Use ECS ephemeral storage.
--aws-ephemeral-storage-size	25	Ephemeral storage size in GB.

The AWS provider uses the standard AWS credential chain, including environment variables, shared profiles, SSO sessions, and runner roles.

Kubernetes

game-ci orchestrate ./my-unity-project \
  --provider-strategy k8s \
  --target-platform StandaloneLinux64 \
  --kube-config "$KUBE_CONFIG_BASE64" \
  --kube-volume-size 25Gi

Common Kubernetes options:

Option	Default	Description
--kube-config	empty	Kubeconfig content or path.
--kube-volume	empty	Existing persistent volume name.
--kube-volume-size	25Gi	Persistent volume size.
--kube-storage-class	empty	Kubernetes storage class.
--container-namespace	default	Kubernetes namespace.

Custom Jobs

Use --custom-job when the provider should run commands that do not map to a built-in engine build or test command.

game-ci orchestrate ./my-godot-project \
  --provider-strategy local-docker \
  --custom-job '- name: godot-export
  image: barichello/godot-ci:4.3
  commands: |
    godot --headless --export-release "Linux/X11" /build/output/game'

Provider Executables

Custom providers can also be exposed through an executable that speaks the Orchestrator CLI provider protocol. Load the executable as a plugin and select the generated provider strategy:

game-ci \
  --plugin executable:./my-provider \
  orchestrate ./my-project \
  --provider-strategy cli-protocol

For protocol details, see CLI provider protocol.

Config-Defined Providers

Because the Orchestrator is a built-in plugin, provider strategies can also point at YAML or JSON provider configuration files without any extra setup:

game-ci orchestrate ./my-project \
  --provider-strategy config:./.game-ci/providers/local-shell.yml

Use this when a provider can be described as lifecycle commands that call existing scripts, CLIs, or automation APIs. See Config-defined providers for the file format, runtime environment variables, and examples.

Configuration Files

Orchestrated jobs can load common options from .game-ci.yml:

cliOptions:
  providerStrategy: local-docker
  targetPlatform: StandaloneLinux64

Then the command can stay short:

game-ci orchestrate ./my-project

Provider-specific options are registered by the built-in Orchestrator plugin, so run with --help to inspect the exact option set available in your installed version.

See Also

• Orchestrate: advanced topics — caching, middleware/hooks, build retry, and the engine launch wrapper
• Engine commands — core build/test/activate
• Configuration and plugins