Runners & OS Resolution

🖥️ Runner & OS Selection Guide

This guide explains how the Unity CI pipeline determines which GitHub Actions runner to use for each job. It supports both GitHub-hosted and self-hosted runners with dynamic OS resolution.

⚠️ Note:
As of now, main_runner should be set to an Ubuntu-based runner (ubuntu-latest or a compatible self-hosted Linux label).
The game-ci/unity-builder@v4 action uses Docker and only supports Linux hosts.
Using windows-* or macos-* as main_runner will cause Docker-based builds (e.g. WebGL, Android) to fail.

---

🧠 Runner Resolution Logic

The pipeline uses two main runner variables:

• main_runner — used for general jobs like testing, WebGL, Windows, and Linux builds.
• macos_runner — used when a job requires macOS, such as iOS builds or TestFlight deployments.

🔄 Resolution Priority (per runner)

1. Not Set (Fallback to Default)
   If no runners are defined, the workflow uses GitHub-hosted defaults.

2. Repository Variable
   If main_runner or macos_runner is defined in your repository under
   Settings → Actions → Variables, that value takes priority.

3. GitHub-hosted Runner Match
   If the value matches a GitHub-hosted runner name (e.g., ubuntu-latest, macos-latest), it will use that.

4. Self-hosted Runner Fallback
   If not a GitHub-hosted runner, the workflow looks for a self-hosted runner with a matching label.

5. Fail if Not Found
   If no matching runner is found, the job will fail.

---

⚙️ Default Behavior (If No Variables Are Set)

If neither main_runner nor macos_runner is configured, these defaults apply:

main_runner = ubuntu-latest
macos_runner = macos-latest

This ensures GitHub-hosted compatibility by default.

---

🔗 Runner Configuration Reference

The list of supported runner OS mappings is maintained in the repository:

➡️ .github/actions/resolve-runners/runners.json

This file defines which GitHub Actions runner should be used for each OS type and is used internally by the resolve-runners action to dynamically select appropriate run

---

🏷️ Example Configurations

✅ Use GitHub-hosted Runners (Recommended Default)

main_runner = ubuntu-latest
macos_runner = macos-latest

🛠️ Use Self-hosted Runners

main_runner = unity-selfhosted
macos_runner = macos-unity-runner

Note: Ensure your self-hosted runners are registered with these exact labels.
If not found, the workflow will fail.

---

📦 Where Runner Values Are Used

These runner values are passed into reusable workflows, including:

• run-tests.yml
• build-project.yml
• summarize-build.yml
• deploy.yml

Inside those workflows, the runner input is used like this:

runs-on: ${{ inputs.runnerMain }}

This setup enables full flexibility between GitHub-hosted and self-hosted runners.