Skip to main content
Version: v3

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

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 and Hub are installed in runtime, leading to longer build times. Should it become an issue, consider using macos-runner instead.

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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos'
            editor_version: '2021.3.2f1'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos'
            resource_class: 'large'
  • Default: medium
  • Required: False
  • Type: Enum

xcode_version​

Choose the xcode version for your execution environment.

version: 2.1

orbs:
  unity: game-ci/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos'
            xcode_version: '14.0.0'
  • Default: 13.4.1
  • 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 hardware 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos-runner'
            editor_version: '2021.3.2f1'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos-runner'
            resource_class: 'my_runner_resource_class'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos-runner'
            working_directory: '/var/opt/circleci/unity_working_dir'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/ubuntu'
            editor_version: '2021.3.2f1'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos'
            resource_class: 'large'
  • Default: medium
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/macos'
            target_platform: 'linux-il2cpp'
  • 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/[email protected]

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'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/windows-2022'
            ## or name: "unity/windows-2019"
            ## or name: "unity/windows-2019-cuda"
            resource_class: 'xlarge'
  • 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/[email protected]

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'
  • 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 hardware 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/windows-runner'
            editor_version: '2021.3.2f1'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/windows-runner'
            resource_class: 'my_runner_resource_class'
  • 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/[email protected]

workflows:
  build-unity-project:
    jobs:
      - unity/build:
          executor:
            name: 'unity/windows-runner'
            working_directory: 'C:\Users\circleci\AppData\Local\Temp\Unity_Working_Dir'
  • Default: C:\Users\circleci\AppData\Local\Temp\Workdir
  • Required: False
  • Type: String