Executors
The Orb provides reusable execution environments for you to run your jobs on. The executors available are macOS, macOS on Runner, Windows, Windows on Runner, Ubuntu on Docker and Ubuntu on container runner.
The examples on this page use a context named unity. Replace it with the name of the context that
holds your Unity credentials, as set up in Activation.
The macos and windows executors take longer to setup due to the installation of external
dependencies. This can be mitigated using their Runner
variants. As Runner doesn't share the ephemeral nature of the CircleCI cloud executors, the external
dependencies will already be installed after the first run, decreasing the environment preparation
time.
Notice that projects using IL2CPP as the
scripting backend should run on the same
OS as the build target. For example, if you want to build for
macOS using IL2CPP, you must use the macos or macos-runner executors.
For other use-cases, it's recommended to use ubuntu for all supported platforms as it
will be cheaper and faster.
macos
This executor uses the macOS cloud executor and it's recommended for macOS IL2CPP builds. As there are no GameCI images for macOS at the moment, the Unity Editor is installed at runtime with the Unity CLI, leading to longer build times. Should it become an issue, consider using macos-runner instead.
The executor runs on Apple silicon and installs the Apple silicon editor, available from Unity 2021.2. Older editors such as 2020.3 can't be installed on it.
editor_version
Choose the Unity Editor version that you want to use to build your project. The options available can be found on the Unity archive.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/macos'
editor_version: '2021.3.2f1'
build-target: StandaloneOSX
context: unity
- Default:
N/A - Required:
True - Type:
String
resource_class
Choose the resource class for your execution environment. Try increasing it if your environment is running out of memory during the build.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/macos'
editor_version: '2022.3.33f1'
resource_class: 'm4pro.large'
build-target: StandaloneOSX
context: unity
- Options:
m4pro.medium,m4pro.large - Default:
m4pro.medium - Required:
False - Type:
Enum
xcode_version
Choose the Xcode version for your execution environment.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/macos'
editor_version: '2022.3.33f1'
xcode_version: '16.4.0'
build-target: StandaloneOSX
context: unity
- Default:
16.4.0 - Required:
False - Type:
String
macos-runner
This executor uses self-hosted runner. If you are
unsure how to create or configure it, follow
Installing Self-Hosted Runners with the Web App and
CircleCI Self-hosted Runner Installation on macOS.
The macos-runner is an excellent alternative over macos to build macOS IL2CPP with
faster build times. Its non-ephemeral nature saves times on installing external dependencies after
the first run. And in addition, you are free to use an agent with specs exceeding the
available for the
web macOS executor.
editor_version
Choose the Unity Editor version that you want to use to build your project. The options available can be found on the Unity archive.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/macos-runner'
editor_version: '2021.3.2f1'
resource_class: 'my-namespace/my-macos-runner'
build-target: StandaloneOSX
context: unity
- Default:
N/A - Required:
True - Type:
String
resource_class
Enter your runner resource class. If you are unsure what this means, navigate to the beginning of this sub-section.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/macos-runner'
resource_class: 'my-namespace/my-macos-runner'
editor_version: '2022.3.33f1'
build-target: StandaloneOSX
context: unity
- Default:
N/A - Required:
True - Type:
String
working_directory
Enter the working directory of your runner agent. This will be where the job steps will run.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/macos-runner'
working_directory: '/var/opt/circleci/unity_working_dir'
editor_version: '2022.3.33f1'
resource_class: 'my-namespace/my-macos-runner'
build-target: StandaloneOSX
context: unity
- Default:
/var/opt/circleci/workdir - Required:
False - Type:
String
ubuntu
This executor uses the
Docker cloud executor with GameCI
images. Since the latter ships with the Unity Hub, Editor and all
necessary dependencies, none of it is installed in runtime - making ubuntu more time-efficient
than macos and windows.
For faster and cheaper runs, use it for all build targets that don't require a host OS other than Linux.
editor_version
Choose the Unity Editor version that you want to use to build your project. The available options can be found on the versions page.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/ubuntu'
editor_version: '2021.3.2f1'
target_platform: 'linux-il2cpp'
build-target: StandaloneLinux64
context: unity
- Default:
N/A - Required:
True - Type:
String
resource_class
Choose the resource class for your execution environment. Try increasing it if your environment is running out of memory during the build.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/ubuntu'
resource_class: 'large'
target_platform: 'linux-il2cpp'
editor_version: '2022.3.33f1'
build-target: StandaloneLinux64
context: unity
- Default:
large - Required:
False - Type:
Enum
target_platform
Choose the target platform to be used for the GameCI image. The available options can be found on the versions page.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/ubuntu'
target_platform: 'linux-il2cpp'
editor_version: '2022.3.33f1'
build-target: StandaloneLinux64
context: unity
- Default:
N/A - Required:
True - Type:
Enum
windows
This executor uses the Windows cloud executor with GameCI images and it's recommended for Windows IL2CPP builds. Due to limitations, jobs running on the Windows executor must install third-party dependencies in runtime, leading to longer build times. Should it become an issue, consider using windows-runner instead.
The orb ships with three variants:
windows-2019,
windows-2019-cuda and
windows-2022. If you are
unsure of which one to use, pick windows-2022. If you need an executor with GPU, then choose
windows-2019-cuda.
editor_version
Choose the Unity Editor version that you want to use to build your project. The available options can be found on the versions page.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/windows-2022'
## or name: "unity/windows-2019"
## or name: "unity/windows-2019-cuda"
editor_version: '2021.3.2f1'
target_platform: 'windows-il2cpp'
build-target: StandaloneWindows64
context: unity
- Default:
N/A - Required:
True - Type:
String
size
Choose the size of your execution environment resource class. Try increasing it if your environment is running out of memory during the build.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/windows-2022'
## or name: "unity/windows-2019"
## or name: "unity/windows-2019-cuda"
size: 'xlarge'
target_platform: 'windows-il2cpp'
editor_version: '2022.3.33f1'
build-target: StandaloneWindows64
context: unity
- Default:
large - Required:
False - Type:
Enum
target_platform
Choose the target platform to be used for the GameCI image. The available options can be found on the versions page.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/windows-2022'
## or name: "unity/windows-2019"
## or name: "unity/windows-2019-cuda"
target_platform: 'windows-il2cpp'
editor_version: '2022.3.33f1'
build-target: StandaloneWindows64
context: unity
- Default:
N/A - Required:
True - Type:
Enum
windows-runner
This executor uses self-hosted runner. If you are
unsure how to create or configure it, follow
Installing Self-Hosted Runners with the Web App and
CircleCI Self-hosted Runner Installation on Windows.
The windows-runner is an excellent alternative over windows to build Windows IL2CPP
with faster build times. Its non-ephemeral nature saves times on installing external dependencies
after the first run. And in addition, you are free to use an agent with specs exceeding the
available for the web Windows
executor.
editor_version
Choose the Unity Editor version that you want to use to build your project. The available options can be found on the versions page.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/windows-runner'
editor_version: '2021.3.2f1'
target_platform: 'windows-il2cpp'
resource_class: 'my-namespace/my-windows-runner'
build-target: StandaloneWindows64
context: unity
- Default:
N/A - Required:
True - Type:
String
resource_class
Enter your runner resource class. If you are unsure what this means, navigate to the beginning of this section.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/windows-runner'
resource_class: 'my-namespace/my-windows-runner'
target_platform: 'windows-il2cpp'
editor_version: '2022.3.33f1'
build-target: StandaloneWindows64
context: unity
- Default:
N/A - Required:
True - Type:
String
working_directory
Enter the working directory of your runner agent. This is be where the job steps will run from.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/windows-runner'
working_directory: 'C:\Users\circleci\AppData\Local\Temp\Unity_Working_Dir'
target_platform: 'windows-il2cpp'
editor_version: '2022.3.33f1'
resource_class: 'my-namespace/my-windows-runner'
build-target: StandaloneWindows64
context: unity
- Default:
C:\ProgramFiles\CircleCI\Workdir - Required:
False - Type:
String
ubuntu-container-runner
This executor runs the same GameCI images as ubuntu, but on
your own container runner instead of
CircleCI's cloud. It takes the same editor_version and target_platform parameters as
ubuntu.
resource_class
The fully qualified resource class of your container runner, in the form namespace/name.
version: 2.1
orbs:
unity: game-ci/unity@2
workflows:
build-unity-project:
jobs:
- unity/build:
executor:
name: 'unity/ubuntu-container-runner'
resource_class: 'my-namespace/my-container-runner'
target_platform: 'linux-il2cpp'
editor_version: '2022.3.33f1'
build-target: StandaloneLinux64
context: unity
- Default:
N/A - Required:
True - Type:
String