⚙️ Lesson 8.2: Automated & Cloud Builds (CI/CD)

What CI/CD Buys You

Continuous Integration (CI) means every change pushed to the repository is automatically built and tested by a server, so integration problems surface within minutes of the commit that caused them. Continuous Delivery/Deployment (CD) extends that: a successful build is automatically packaged and handed to testers, a store, or players.

The concrete wins: builds are reproducible (a clean checkout on a clean machine, not your cluttered working copy), guarded (the pipeline runs Lesson 8.1's tests and refuses to ship a red build), and parallel (Windows, macOS, Android, and WebGL players from one push while you keep working). The moment a teammate breaks the build, everyone knows — not three days later when someone tries to make a release.

Driving Unity from the Command Line

Every automated Unity build rests on one fact: the Editor can run without its window, driven entirely by command-line arguments. This is batch mode. The canonical invocation:

Unity -batchmode -quit -nographics \
      -projectPath /path/to/Project \
      -buildTarget StandaloneWindows64 \
      -executeMethod BuildScript.PerformBuild \
      -logFile -

Each flag earns its place:

• -batchmode — no interactive Editor UI; suppresses dialogs so nothing blocks waiting for a click.
• -quit — exit the Editor when the invoked method returns (omit it and the process hangs open forever on the runner).
• -nographics — don't initialise a graphics device; fine for building and headless tests on a GPU-less server.
• -projectPath — which project to open.
• -buildTarget — the platform to switch to before building (e.g. StandaloneWindows64, StandaloneOSX, Android, WebGL).
• -executeMethod — a public static method Unity calls once the project is open; this is your entry point into custom build code.
• -logFile - — stream the Editor log to stdout so the CI console shows what happened.

To run the test suite headlessly instead of building, swap in -runTests -testPlatform EditMode -testResults results.xml. Unity exits with a non-zero code if any test fails — which is exactly what lets CI gate the build on green tests.

A C# BuildScript

The -executeMethod target is ordinary Editor C#. It lives in an Editor folder (or Editor-only assembly) and uses BuildPipeline.BuildPlayer to produce the player. Here is a complete, CI-ready script:

using UnityEditor;
using UnityEditor.Build.Reporting;
using UnityEngine;

public static class BuildScript
{
    // The scenes to include, in order. Pulling from the Build Settings list
    // keeps this in sync with what you test in the Editor.
    private static string[] Scenes =>
        System.Array.FindAll(EditorBuildSettings.scenes, s => s.enabled)
            .Length == 0
            ? new[] { "Assets/Scenes/Main.unity" }
            : System.Array.ConvertAll(
                System.Array.FindAll(EditorBuildSettings.scenes, s => s.enabled),
                s => s.path);

    // Called by: -executeMethod BuildScript.PerformBuild
    public static void PerformBuild()
    {
        // Allow CI to override the output path via an env var.
        string outDir = System.Environment.GetEnvironmentVariable("BUILD_OUTPUT")
                        ?? "Builds/Windows";
        string exePath = $"{outDir}/MyGame.exe";

        var options = new BuildPlayerOptions
        {
            scenes = Scenes,
            locationPathName = exePath,
            target = BuildTarget.StandaloneWindows64,
            options = BuildOptions.None   // add BuildOptions.Development for dev builds
        };

        BuildReport report = BuildPipeline.BuildPlayer(options);
        BuildSummary summary = report.summary;

        if (summary.result == BuildResult.Succeeded)
        {
            Debug.Log($"Build OK: {summary.totalSize} bytes in {summary.totalTime}");
            EditorApplication.Exit(0);
        }
        else
        {
            Debug.LogError($"Build FAILED with {summary.totalErrors} errors");
            EditorApplication.Exit(1);   // non-zero → CI marks the job failed
        }
    }
}

The shape is always the same: assemble a BuildPlayerOptions (scenes, output path, target, options), call BuildPipeline.BuildPlayer, inspect the returned BuildReport, and translate its result into a process exit code. Reading the output path from an environment variable lets the same script serve every platform your CI matrix builds — the pipeline sets BUILD_OUTPUT, the script obeys.

💡 The BuildReport is a goldmine. Beyond pass/fail, report exposes per-step timings and a breakdown of what went into the build. Logging summary.totalSize over time is a cheap way to catch the day someone accidentally ships 2 GB of uncompressed textures.

The Pipeline, End to End

Before wiring specific tools, hold the whole flow in your head. A push triggers the runner, which checks out the commit, runs the tests from Lesson 8.1, and only if they're green invokes the build script above — then publishes the resulting player as a downloadable artifact and, optionally, deploys it.

Figure 1: A Unity CI/CD pipeline. A commit triggers a fresh runner that activates a license, runs the test suite, and gates the build on green tests. A passing build becomes a versioned artifact and can flow on to deployment. The red branch stops the line and alerts the team — the whole point of CI.

Every CI system — GitHub Actions, GitLab CI, Unity Build Automation — is a way of expressing this same graph. Learn the shape once and the specific YAML is just dialect.

GitHub Actions with game-ci

The most common self-service option is GitHub Actions driving the open-source GameCI actions, which package Unity into Docker images and handle the batch-mode plumbing for you. A workflow file lives at .github/workflows/build.yml. Here's a minimal test-then-build pipeline:

name: Build
on: [push]

jobs:
  test-and-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          lfs: true                 # Git LFS for large assets

      - name: Run tests
        uses: game-ci/unity-test-runner@v4
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          testMode: editmode

      - name: Build
        uses: game-ci/unity-builder@v4
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          targetPlatform: StandaloneWindows64
          buildMethod: BuildScript.PerformBuild

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: MyGame-Windows
          path: build/

Read it as the graph from Figure 1: check out (with LFS for big assets), run the Edit Mode tests, build calling your BuildScript.PerformBuild, then upload the output folder as a downloadable artifact. The unity-builder action supplies the Docker image with the right Unity version, invokes batch mode, and injects the license from a secret — so you never write the raw -batchmode command yourself, but everything under the hood is exactly the flags from earlier in this lesson.

Licensing & Activation in CI

Unity refuses to run headlessly without an activated license, and a CI runner is a throwaway machine with no logged-in user — so activation is the step that trips up every first pipeline. The mechanism depends on your license type:

Whichever path, the license lands in encrypted secrets, never in the repository. Treat a leaked .ulf or serial like a leaked password.

Unity Build Automation

If you'd rather not manage runners, licenses, and Docker images yourself, Unity Build Automation (part of Unity Gaming Services, and the successor to what was called Cloud Build) is Unity's hosted build farm. You connect your Git repository through the Unity Dashboard, define build targets per platform, and Unity's servers build on every push — including notoriously fiddly platforms like iOS, where they manage the macOS + Xcode toolchain for you.

The trade-off is the usual build-vs-buy: a managed service means less setup and no infrastructure to babysit, but less control and a usage-based cost as your team and build frequency grow. Many studios start on Build Automation for convenience and move to self-hosted GitHub Actions once they need custom steps or want to control cost. Both drive the very same BuildScript.PerformBuild you wrote — the build logic is portable; only the orchestration changes.

🔎 It's a spectrum, not a binary. GitHub-hosted runners, self-hosted runners, and Unity Build Automation trade convenience against control and cost in that order. Pick by what's scarce on your team: if it's time and ops skill, lean managed; if it's money and you need bespoke steps, lean self-hosted.

Artifacts & Versioning

A build the pipeline throws away is useless; the output must become a durable, identifiable artifact. Two habits make artifacts trustworthy:

Stamp every build with a version. Set PlayerSettings.bundleVersion and the platform build number from the pipeline — a common scheme is a semantic version from a git tag plus the CI run number and short commit hash, e.g. 1.4.0+312.a1b9c4. Now any binary a tester reports a bug in maps back to an exact commit.

// Called early in PerformBuild, before BuildPlayer.
string version = System.Environment.GetEnvironmentVariable("BUILD_VERSION") ?? "0.0.0";
string build   = System.Environment.GetEnvironmentVariable("GITHUB_RUN_NUMBER") ?? "0";
PlayerSettings.bundleVersion = version;
PlayerSettings.macOS.buildNumber = build;
PlayerSettings.Android.bundleVersionCode = int.Parse(build);

Name and retain artifacts deliberately. Upload the player folder under a name that includes platform and version (MyGame-Win64-1.4.0-312.zip), and set a retention policy so you can always fetch the exact build a report references. Artifacts are also how CD hands off downstream — the same zip a tester downloads is the one a deploy step pushes to a store channel.

Hands-on Challenge

public static void PerformBuild()
{
    string which = System.Environment.GetEnvironmentVariable("BUILD_TARGET") ?? "Windows";
    var opts = new BuildPlayerOptions { scenes = Scenes };

    if (which == "WebGL")
    {
        opts.target = BuildTarget.WebGL;
        opts.locationPathName = "Builds/WebGL";       // a folder
    }
    else
    {
        opts.target = BuildTarget.StandaloneWindows64;
        opts.locationPathName = "Builds/Windows/MyGame.exe";
    }

    var report = BuildPipeline.BuildPlayer(opts);
    EditorApplication.Exit(report.summary.result == BuildResult.Succeeded ? 0 : 1);
}

Summary

🚀 What's Next?

Your game now builds and tests itself on every push. But shipping isn't the end — it's the start of the loop where you learn what players actually do. In Lesson 8.3: Live-Ops — Analytics, Remote Config & Crash Reporting you'll see how to measure real player behaviour, change balancing and feature flags without a new build, and catch crashes in the wild — turning a shipped build into a game you keep improving.