Orchestrated Jobs

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.

<<<<<<< HEAD

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

=======

Remote Run vs Standalone Orchestrate

Use game-ci remote run from the public CLI for normal remote 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. It is not the preferred public CLI command.

Need	Use
Friendly public CLI command for builds, tests, or jobs	game-ci remote run
Backwards-compatible old remote command name	game-ci remote build

origin/docs/unity-reliability-guide | Direct standalone Orchestrator provider execution | game-ci orchestrate | | Executable provider protocol integration with GameCI CLI | game-ci serve in the provider tool |

Orchestrator Plugin

The Orchestrator is the default provider backend for provider-backed execution. Load it as a CLI plugin:

game-ci \
  --plugin @game-ci/orchestrator-plugin \
  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-system	Run directly on the current machine.
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.

<<<<<<< HEAD

| Config-defined | config:<path> | Map lifecycle commands from YAML or JSON. |

origin/docs/unity-reliability-guide

Local Docker

game-ci \
  --plugin @game-ci/orchestrator-plugin \
  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.

AWS

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

game-ci \
  --plugin @game-ci/orchestrator-plugin \
  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 \
  --plugin @game-ci/orchestrator-plugin \
  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 \
  --plugin @game-ci/orchestrator-plugin \
  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

When the Orchestrator plugin is loaded, provider strategies can also point at YAML or JSON provider configuration files:

game-ci \
  --plugin @game-ci/orchestrator-plugin \
  remote run ./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 the provider plugin and common options from .game-ci.yml:

cliOptions:
  plugins:
    - '@game-ci/orchestrator-plugin'
  providerStrategy: local-docker
  targetPlatform: StandaloneLinux64

Then the command can stay short:

game-ci orchestrate ./my-project

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