DEV Community: Alon Farchy

Deploying Unity Builds to Google Play Store with Buildalon

Alon Farchy — Mon, 16 Feb 2026 16:03:21 +0000

Getting your game onto the Google Play Store involves a complex dance of signing keys, version codes, and console configurations. Manually building an Android App Bundle (AAB), signing it, and uploading it to the Play Console every time you want to test a change is a recipe for burnout.

In this guide, we'll walk through how to automate your Unity builds for Android and deploy them directly to the Google Play Store internal testing track using GitHub Actions.

Prerequisites
Setup Overview
Setting up Google Play Console
Configuring Google Cloud Access
Handling the Keystore
Updating the Build Pipeline
Deploying to Internal Testing
Installing the Internal App and Inviting Testers
About Buildalon

Prerequisites

Before we start, make sure you have:

Google Play Developer Account: You need to be able to access the Google Play Console.
Working Unity Build: You should have a basic automated build pipeline set up. Check out our GitHub Actions Unity guide if you're starting from scratch.

Setup Overview

Automating Android deployments involves two key security components: Android Keystores (for Android Signing) and Service Accounts.

App Registration: Create the app placeholder in Google Play Console.
Authentication: We'll use Workload Identity Federation to securely authenticate GitHub Actions Android workflows with Google Cloud.
Keystore: We need to securely provide our signing keystore to the build server.
Build & Upload: We'll update the workflow to build an Android App Bundle (.aab) and upload it.

Setting up Google Play Console

First, let's make sure Google is expecting our app.

Log in to Google Play Console.
Click Create app.
Fill in the app details (Name, Default language, Game/App type).
Important: Manually build your APK/AAB in Unity and upload it to the Internal Testing track via the web interface. This initializes the track, sets the Package Name permanently, and allows you to answer the initial regulatory questions (Data Safety, etc.).

Configuring Google Cloud Access

To allow GitHub Actions to upload via the API, we need to link our Google Play account to a Google Cloud project. We will use a modern, secure method called Workload Identity Federation.

1. Enable the Google Play Android Developer API

Go to the Google Cloud Console.
Select or create a project for your game.
Search for Google Play Android Developer API and enable it.

2. Create a Service Account

In Google Cloud Console, go to IAM & Admin > Service Accounts.
Click Create Service Account.

Name it something like unity-cicd-uploader and click Create and Continue.
Skip the role assignment steps (click Continue then Done). This service account does not need specific Google Cloud permissions, only Google Play permissions.
Copy the email address (e.g., unity-cicd-uploader@my-project.iam.gserviceaccount.com).
Go back to Google Play Console > Users and permissions and invite this email.
In the permissions tab, grant it App Access to your game, and under Account permissions, ensure it has Releases to play store > Release to testing tracks (or Admin if you want full control).

3. Setup Workload Identity Federation

Next we need to give have the action runner authenticate with the service account we created. A secure way to do this is to use Workload Identity Federation, which procides an secure authentication scheme between GitHub Actions and Google Cloud.

In Google Cloud Console, go to IAM & Admin > Workload Identity Federation.
Create a Pool (e.g., unity-cicd-pool).
Create a Provider inside that pool:
- Type: OpenID Connect (OIDC)
- Provider name: unity-cicd-provider (or any descriptive name - you will reference it in the workflow)
- Issuer (URL): https://token.actions.githubusercontent.com
- Audience: sts.amazonaws.com (Standard default for GitHub Actions).
- Provider attributes (attribute mapping):
- google.subject = assertion.sub
- attribute.repository = assertion.repository
- attribute.ref = assertion.ref
- attribute.actor = assertion.actor
- Condition: Use a minimal repo lock like attribute.repository == "owner/repo", for example attribute.repository == "virtualmaker-net/proxima"
After creating the provider, go back to the page for your pool and at the top click Grant Access. Select Grant access using service account impersonation and choose your service account created in the previous section. Set the principals to repository and the value to your owner/repo.

Handling the Keystore

Your Android Keystore is the identity of your app. If you lose it, you can't update your app. If it's stolen, someone else can update your app.

For CI/CD, we have two common approaches:

Base64 Encode: Encode the .keystore file to a base64 string and store it as a GitHub Secret.
Repo Storage: Commit the keystore file to your repository (if private) or encrypted.

Method 1: Base64 Encoding (Recommended)

This method keeps your keystore out of your repository entirely.

Encode: Run one of the following commands to turn your file into a text string.

macOS / Linux:

openssl base64 -in user.keystore -out user.keystore.base64.txt

Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("user.keystore")) | Set-Content user.keystore.base64.txt

Store: Copy the contents of the text file and add it as a secret named ANDROID_KEYSTORE_BASE64.

Method 2: Repo Storage

You can commit the keystore file to your repository (e.g. in Assets/Keys/user.keystore), but this is risky. If your repo is ever compromised or made public, your signing key is exposed. If you choose this route, ensure your .gitignore does not ignore .keystore files.

Regardless of the method, go to your GitHub Repository > Settings > Secrets and variables > Actions and add:

ANDROID_KEYSTORE_PASSWORD: The password for your keystore.
ANDROID_KEYALIAS_PASSWORD: The password for your key alias (often the same as the keystore, but not always).

Updating the Build Pipeline

Now let's update our workflow to include the Android build, Google Cloud authentication, and Play Store upload steps. We'll be using the following actions:

google-github-actions/auth - Authenticates with Google Cloud via Workload Identity Federation.
RageAgainstThePixel/upload-google-play-console - Uploads an AAB to the Google Play Console.

Create or update your .github/workflows/unity-build.yml file with the following configuration:

name: Deploy to Google Play

on:
  push:
    branches:
      - main

# Required for Workload Identity Federation
permissions:
  id-token: write
  contents: read

jobs:
  build-and-deploy:
    name: Build & Deploy to Google Play
    runs-on: buildalon-windows

    steps:
      # Checkout the repository
      - uses: actions/checkout@v6
        with:
          lfs: true

      # Setup Unity with Android build support
      - uses: buildalon/unity-setup@v2
        with:
          build-targets: Android

      # Activate Unity License
      - uses: buildalon/activate-unity-license@v2
        with:
          license: 'Personal'
          username: ${{ secrets.UNITY_EMAIL }}
          password: ${{ secrets.UNITY_PASSWORD }}

      # Add the Buildalon command line package to your Unity project
      - name: Add Build Pipeline Package
        working-directory: ${{ env.UNITY_PROJECT_PATH }}
        run: |
          npm install -g openupm-cli
          openupm add com.virtualmaker.buildalon

      # Decode base64 keystore from GitHub Secrets
      - name: Decode Keystore
        run: |
          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | openssl base64 -d -out ${{ github.workspace }}/user.keystore

      # Build the Android App Bundle (.aab)
      - uses: buildalon/unity-action@v3
        name: Build Android AAB
        with:
          build-target: Android
          args: >-
            -quit -batchmode
            -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild
            -keystorePath ${{ github.workspace }}/user.keystore
            -keystorePass "${{ secrets.ANDROID_KEYSTORE_PASSWORD }}"
            -keyaliasName "my-key-alias"
            -keyaliasPass "${{ secrets.ANDROID_KEYALIAS_PASSWORD }}"
            -appBundle
          log-name: Android-Build

      # Authenticate with Google Cloud using Workload Identity Federation
      - uses: google-github-actions/auth@v3
        with:
          # The service account email from Google Cloud
          service_account: unity-cicd-uploader@my-project.iam.gserviceaccount.com
          # The full resource name of the Workload Identity Provider
          workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/unity-cicd-pool/providers/unity-cicd-provider

      # Java is required by the Play Console upload tool
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: 21

      # Upload the AAB to the Google Play Internal Testing track
      - uses: RageAgainstThePixel/upload-google-play-console@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

          # Directory containing the .aab file
          release-directory: ${{ env.UNITY_PROJECT_PATH }}/Builds/Android

          # The track to upload to (internal, alpha, beta, production)
          track: internal

          # Draft status lets you review before rolling out
          status: draft

          # Optional release notes
          metadata: |
            {
              "releaseNotes": {
                "language": "en-US",
                "text": "${{ env.RELEASE_NOTES }}"
              }
            }

Key Steps Explained

Decode Keystore: Converts the base64-encoded keystore secret back into a file for signing. If you checked in your keystore, you can skip this step.
Build Android AAB: Runs the Unity build with keystore credentials and -appBundle to produce an .aab instead of an .apk. Replace my-key-alias with the alias you chose when creating your keystore in Unity (Project Settings > Player > Publishing Settings).
Authenticate with Google Cloud: Uses Workload Identity Federation to get a short-lived token. You need to replace two values:
- service_account: The email address from step 2.5 above (visible on the Service Account details page in Google Cloud Console under IAM & Admin > Service Accounts).
- workload_identity_provider: The full resource name of the provider. You can find this in IAM & Admin > Workload Identity Federation, click your pool, then click your provider, and copy the Default audience or Resource name value. It follows the format projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID. Your Project Number (not Project ID) is on the Google Cloud Console Dashboard or Project Settings page.
Upload to Play Console: Pushes the .aab to the internal testing track as a draft, so your team can test immediately.

NOTE: We are deploying to the internal track. This is usually the best place for automated builds so your team can test them immediately.

Deploying to Internal Testing

Once you push these changes, your workflow should:

Build the Android App Bundle (.aab).
Authenticate with Google Cloud.
Upload the .aab to the Internal Testing track on the Play Console.

When the upload finishes, your testers in the Internal Testing email list will receive an update (or see it in the Play Store if they have it installed).

Common Gotchas

Android Version Code: Google Play requires a unique integer versionCode for every single upload. Ensure your build script increments this on every build (e.g., using ${{ github.run_number }}) in your Unity Android Build settings or build script.
Android Build Number: Similar to versionCode, the user-visible bundleVersion (or Unity App Version) should be updated to help testers identify which build they are on.
Play App Signing: When you create your app in the console, you likely opted into Play App Signing. This means Google manages the key used to sign APKs delivered to users. The keystore we configured above is your Upload Key. If you lose it, you can contact Google support to reset it, whereas the final signing key is safely stored by Google.
API Delays: Sometimes the Google Play API takes a few minutes to process a new build.
Permissions: If you get a 403 error, double-check that the Service Account email is added to the Google Play Console Users with the correct permissions and linked to the Google Cloud project.

Installing the Internal App and Inviting Testers

After your first successful upload to the internal track, you need to explicitly invite testers and share the opt-in link.

Invite Internal Testers

In the Google Play Console:

Open your app and go to Testing > Internal testing.
Open the Testers tab.
Create an email list (or select an existing one) and add tester emails.
Save the list and make sure it is attached to your internal test track.
Copy the Opt-in URL from the internal testing page.

Share that opt-in URL with your testers. They must accept the invite using the same Google account you added to the tester list.

How Testers Install the Internal Version

Tester opens the opt-in URL and taps Become a tester.
Tester taps the Play Store link shown on that page.
Tester installs the app (or updates it if already installed).

If the app is already installed from another source (for example, a local APK), the tester may need to uninstall it first if the signing key or package signature does not match the Play build.

For later releases, once users are opted in, they usually receive updates through the Play Store automatically (or via manual update if auto-update is disabled).

About Buildalon

Buildalon provides verified GitHub Actions and dedicated build infrastructure to streamline Unity development. Register for Buildalon to get support with your Unity build automation needs.

Automating Unity Builds for Meta Quest

Alon Farchy — Mon, 26 Jan 2026 16:33:22 +0000

Developing for VR on the Meta Quest involves a lot of iteration. Since many device capabilities only work on the headset, you'll find yourself making frequent builds to sideload. Distributing those builds to play-testers manually can consume much of your time. As your app and team grow, you start wishing this process was automated.

In this guide, we'll set up a completely automated pipeline that takes your code from GitHub, builds it in the cloud, and delivers it directly to a release channel on the Meta Quest Store.

NOTE: This guide assumes you are already familiar with setting up basic Unity builds with GitHub Actions. If you're just starting out, check out my guide on Automating Unity Builds with GitHub Actions first.

By the end of this tutorial, you will have a GitHub Actions workflow that:

Triggers whenever you push to your main branch.
Builds your Unity project for Android (Meta Quest).
Uploads the resulting APK directly to a specific Release Channel (e.g., Alpha) on the Meta Quest Store.

Setting up the Meta Developer Portal
Configure GitHub Secrets for Meta
Configure GitHub Secrets for Keystores and Signing
Update Your Build Workflow
Installing the Build on Your Headset

Setting up the Meta Developer Portal

Before we touch any YAML configuration, we need to prepare our application on the Meta Developer Dashboard.

Create Your App

If you haven't created an app yet:

Log in to the Developer Dashboard.
Click Create New App.
Give it a name and click Create.

Get Your Credentials

To allow GitHub Actions to upload builds on your behalf, you need two pieces of information: the App ID and the App Secret.

Navigate to the Development > API tab in your app's dashboard.
Copy the App ID. You'll need this for your workflow file.
Copy the App Secret. Do not commit this to your repository! We will save this as a secret in GitHub.

TIP: On some accounts, you may need to verify your account or complete the Data Use Checkup before you can access full API functionality. If your upload fails later with permission errors, double-check that your developer account status is in good standing.

Create a Release Channel

Release channels let you to distribute different versions of your app to different users. For example, you might have a "Live" channel for the public and an "Alpha" channel for internal testing.

Go to Distribution > Release Channels.
You likely already have LIVE, ALPHA, BETA, and RC.
You can use one of these (e.g., ALPHA) or create a new one specifically for automated builds, like NIGHTLY or ACTIONS.
Note the exact name of the channel you want to target.

Configure GitHub Secrets for Meta

We never want to hardcode our App Secret into our workflow files where anyone could see them. Instead, we use GitHub Secrets.

Navigate to your GitHub repository.
Click on Settings > Secrets and variables > Actions.
Click New repository secret.
Create a secret named META_APP_SECRET and paste the value you copied from the Meta Developer Dashboard.
(Optional) You can also store your App ID as META_APP_ID, though it is generally considered public information.

Configure GitHub Secrets for Keystores and Signing

One critical detail for Android builds is code signing. The Meta Quest Store requires your APKs to be signed with a production keystore, even for the Alpha channel. If you try to upload a development build signed with a default debug keystore, the action will successfully build, but the Meta server will reject the upload during validation.

What is a Keystore?

A keystore is a binary file that acts as a digital certificate for your app. It proves that the update comes from the same developer as the original app. If you lose your keystore, you lose the ability to update your app on the store—forever. So keep it safe!

Creating a Keystore

Open your Unity project.
Go to Project Settings > Player > Publishing Settings.
Under Keystore Manager, create a new keystore.
Choose a location inside your project folder.
Set a Keystore Password, create a new Key Alias, and set a Key Password.
Go to your GitHub repository Settings > Secrets and variables > Actions.
Create two new secrets for your passwords: ANDROID_KEYSTORE_PASS and ANDROID_KEYALIAS_PASS.

The Buildalon build script we are using is designed to pick up these secrets from the command line arguments and apply them to the keystore found in your project settings.

Keystore Security

For better security, you can encode your keystore in base64 and store it as a GitHub Secret instead of committing the file.

Encode the keystore in base64.

On macOS/Linux:

openssl base64 -in user.keystore -out user.keystore.base64.txt

On Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("user.keystore")) | Set-Content user.keystore.base64.txt

Store: Add it as a secret named ANDROID_KEYSTORE_BASE64.
Decode: Add a step in your workflow (below) to decode it back to a file using openssl base64 -d
Build: Pass -keystorePath user.keystore in your unity-action build arguments.

Update Your Build Workflow

Now, let's look at the workflow file. We'll build upon the standard Buildalon Android workflow but add a crucial final step: the upload.

We'll be using the following actions:

buildalon/setup-ovr-platform-util - Installs OVR Platform Tool.
buildalon/upload-meta-quest-build - Invokes OVR Platform Tool to upload your build.

Create or update your .github/workflows/quest-build.yml file with the following configuration:

name: Deploy to Quest

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    name: Build & Deploy to Quest
    runs-on: buildalon-windows

    steps:
      # Checkout the repository
      - uses: actions/checkout@v4
        with:
          lfs: true

      # Setup Unity
      - uses: buildalon/unity-setup@v1
        with:
          build-targets: Android

      # Activate Unity License
      - uses: buildalon/activate-unity-license@v1
        with:
          license: 'Personal'
          username: ${{ secrets.UNITY_EMAIL }}
          password: ${{ secrets.UNITY_PASSWORD }}

      # Temporarily add the Buildalon command line package to your Unity project
      - name: Add Build Pipeline Package
        working-directory: ${{ env.UNITY_PROJECT_PATH }}
        run: |
          npm install -g openupm-cli
          openupm add com.virtualmaker.buildalon

      # Optional: Decode base64 keystore from GitHub Secrets
      # - name: Decode Keystore
      #   run: |
      #     echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | openssl base64 -d -out ${{ env.UNITY_PROJECT_PATH }}/user.keystore

      # Build the Project
      - uses: buildalon/unity-action@v1
        name: Build Android APK
        with:
          build-target: Android
          # Optional: add a previous step to decode a base64 keystore, and add: -keystorePath ${{ env.UNITY_PROJECT_PATH }}/user.keystore
          args: >-
            -quit -batchmode
            -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild
            -keyaliasPass "${{ secrets.ANDROID_KEYALIAS_PASS }}"
            -keystorePass "${{ secrets.ANDROID_KEYSTORE_PASS }}"
          log-name: Quest-Build

      # Setup OVR Platform Util
      - uses: buildalon/setup-ovr-platform-util@v1

      # Upload to Meta Quest Store
      - uses: buildalon/upload-meta-quest-build@v1
        name: Upload to Meta Quest
        with:
          # Your App ID (can be hardcoded or a secret)
          appId: '123456789012345'

          # Your App Secret
          appSecret: ${{ secrets.META_APP_SECRET }}

          # The path to your built APK.
          buildDir: ${{ env.UNITY_PROJECT_PATH }}/Builds/Android

          # The channel to upload to (ALPHA, BETA, LIVE, etc.)
          releaseChannel: 'ALPHA'

          # Optional, uploads the build even if there are validation errors.
          force: true

Key Changes:

Set the build platform to Android.
Pass the keystore credentials to the build step.
Install the OVR Platform Tools
Upload the built APK.

The magic happens in the buildalon/upload-meta-quest-build step. This action wraps the Oculus Platform Command Line Utility, handling the authentication and upload process for you.

appId: Identifies which application specifically you are updating.
appSecret: Authenticates the upload request.
buildDir: Tells the uploader where to find your build. Note that StartCommandLineBuild by default outputs builds to the Builds/{Platform} folder.
releaseChannel: Ensures the build lands in the right place so your testers get the update without affecting live users.

Installing the Build on Your Headset

Once your build succeeds, it will be uploaded to the ALPHA channel.

Invite Users: In the Meta Developer Dashboard, go to Distribution > Users. Add yourself and your teammates to the ALPHA channel using their Meta account emails.
Accept the Invite: Each person will receive an email invitation to test the app. They must accept this invite.
Find the App:
- Put on your Quest headset.
- Navigate to your App Library.
- Look for the app in the All or Not Installed category. It may also appear in the My Preview Apps section of the Store.
- Install the application.
Confirm the Channel:
- Navigate to the app details in your Library or on the Store page.
- Click the version number to verify or switch the release channel to "ALPHA" (or your chosen channel).

Once installed, future updates from your GitHub Actions pipeline will appear as regular app updates on the headset!

Mission complete!

About Buildalon

Buildalon provides verified GitHub Actions and dedicated build infrastructure to streamline Unity development. Register for Buildalon to get support with your Unity build automation needs.

Automating Unity Builds to iOS, macOS, and visionOS

Alon Farchy — Fri, 16 Jan 2026 12:35:30 +0000

Automating Unity Builds to iOS, macOS, and visionOS

When deploying a Unity game to Apple platforms, you can easily get bogged down with provisioning profiles, signing certificates, and Xcode configuration. It's a time complex consuming process, and manually repeating it for every build is going to eat up your time and slow your team down.

In this guide, we'll walk through how to use GitHub Actions and Buildalon to automate your builds for iOS, macOS, and visionOS, covering everything from setting up your Apple Developer account to creating a workflow that deploys straight to your testers.

Prerequisites
Setup Overview
Setting up App Store Connect
Generating a Build for Sideloading
Deploying to TestFlight

Prerequisites

Before we dive into the automation, there are a few things you'll need:

Apple Developer Account: You need an active membership to deploy to Apple devices or the App Store. Enroll in the Apple Developer Program.
Working Unity Build: You should already have a basic automated build pipeline. If not, follow our Automating Unity Builds with GitHub Actions guide first.

Setup Overview

Automating Xcode builds involves connecting several services with your GitHub workflow. At a high level we need:

Registration: We need to register the App ID and create an app record in App Store Connect so Apple knows what we are building.
Authentication: We will create an App Store Connect API Key to allow GitHub Actions to act on our behalf without 2FA issues.
Update the Build Pipeline:
- Unity Build: Unity runs in batch mode to export an Xcode project. It's important to set the bundleVersion and buildNumber here to track our releases.
- Xcode Build: We use xcodebuild (wrapped in a GitHub Action) to compile, sign, and archive the app into an .ipa (or .app/.pkg for macOS) file.
Distribution: Finally, we either upload the build to TestFlight for beta testing or keep it as an artifact for manual sideloading.

The key to making this easy is the buildalon/unity-xcode-builder action, which handles the complex Xcode build and upload steps for us.

Creating the App on Apple's Portal

Before automation can take over, we need to do a little manual setup to tell Apple about our app. This is a one-time process for each new project.

Log in to App Store Connect.
Go to My Apps.
Click the blue (+) button > New App.
Select your platform (iOS, macOS, or visionOS) and give it a Name.
In the Bundle ID section, you can choose an existing identifier or create a new one. Ensure this matches the Bundle Identifier in your Unity project (e.g., com.mycompany.mygame).
Enter a SKU (a unique tracking ID for your own use) and click Create.

Setting up App Store Connect Authentication

For GitHub Actions to upload builds on your behalf, it needs a secure way to authenticate with Apple. The best way to do this is with an App Store Connect API Key, which avoids the headaches of 2FA in CI environments.

1. Generate an API Key

Head over to App Store Connect.
Go to Users and Access > Integrations > Team Keys.
Click the + button to generate a new key.
Give it a name like "GitHub Actions" and assign the App Manager role.
Download the .p8 file. Keep this safe! You can only download it once.
Take note of the Key ID and your Issuer ID.

2. Base64 Encode the Key

GitHub Secrets can sometimes struggle with the newlines in the .p8 file. A robust way to handle this is to Base64 encode the file content.

Run this command in your terminal (macOS/Linux):

openssl base64 -in AuthKey_XXXXXXXXXX.p8 -out AuthKey_Base64.txt

On Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("AuthKey_XXXXXXXXXX.p8")) | Set-Content AuthKey_Base64.txt

Copy the contents of the generated text file.

3. Add Secrets to GitHub

Go to your repository on GitHub, navigate to Settings > Secrets and variables > Actions, and add the following secrets:

APP_STORE_CONNECT_KEY: The Base64 encoded string from the previous step.
APP_STORE_CONNECT_KEY_ID: The Key ID (e.g., D383SF739).
APP_STORE_CONNECT_ISSUER_ID: The Issuer UUID (e.g., 6053b7fe...).
APPLE_TEAM_ID: Your Team ID (found in Apple Developer Portal under Membership).

If you notice your build failing with authentication errors, double-check that you copied the stored secret correctly and that it doesn't contain any extra whitespace.

Generating a Build for Sideloading

Before messing with TestFlight, it's often easier to just get an installable build (an .ipa for iOS/visionOS, or .app/.pkg for macOS) that you can install directly. This is great for rapid iteration or testing on a few specific devices.

1. The Workflow

Now let's update your build workflow to add steps for building and signing your app. If you don't have a workflow yet, see our Automating Unity Builds article to get started.

Choosing a Runner:
To build for Apple platforms, you must use a macOS runner. You have two main options:

runs-on: macos-latest: GitHub's hosted runners. They are convenient for one-off builds, but can be slow and expensive if you're building frequently.
runs-on: buildalon-macos: Buildalon's runners. These will cache your Unity builds, often completing much faster.

In this example, we'll use buildalon-macos for best performance.

A Note on Build Numbers:
Unity projects use the build number set in the editor (ProjectSettings.asset) by default. In a CI/CD pipeline, it's best practice to override this so every build has a unique identifier. In the example below, we'll use ${{ github.run_number }} as the build number, while keeping the version string (e.g. 1.0) defined in your project settings.

jobs:
  build-iOS:
    name: Build iOS
    runs-on: buildalon-macos
    steps:
      - uses: actions/checkout@v6
        with:
          lfs: true

      # Setup Unity, License, and Build the Project
      # See our "Automating Unity Builds" article for details on these steps
      - uses: buildalon/unity-setup@v2
        with:
          # Use 'iOS', 'Standalone', or 'VisionOS'
          build-targets: iOS

      - uses: buildalon/activate-unity-license@v2
        with:
          license: 'Personal'
          username: '${{ secrets.UNITY_EMAIL }}'
          password: '${{ secrets.UNITY_PASSWORD }}'

      - uses: buildalon/unity-action@v3
        name: Build Unity Project
        with:
          # Use 'iOS', 'StandaloneOSX', or 'VisionOS'
          build-target: iOS
          # Use run_number as the build number (e.g. 1.0.42)
          args: -quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild -buildNumber ${{ github.run_number }}
          log-name: iOS-Build

      # Build the XCode project and sign it
      - uses: buildalon/unity-xcode-builder@v1
        id: xcode-build
        with:
          project-path: ${{ github.workspace }}/Builds/iOS/**/*.xcodeproj
          # 'development' creates a build signed for specific devices
          export-option: development
          team-id: ${{ secrets.APPLE_TEAM_ID }}
          app-store-connect-key: ${{ secrets.APP_STORE_CONNECT_KEY }}
          app-store-connect-key-id: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
          app-store-connect-issuer-id: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}

      - uses: actions/upload-artifact@v6
        with:
          name: iOS-Build
          path: ${{ steps.xcode-build.outputs.executable }}

2. Grab the Artifact

Once the workflow finishes successfully, you can find your build file waiting for you in the Summary page of the workflow run.

The Catch: To install a development build, the destination device's UDID must be registered in the Apple Developer Portal before the build runs. If you get a new device, you'll need to add it to the portal and trigger a fresh build to update the provisioning profile.

3. Installing the Build

Since this is a raw development build, you can't just tap a link to install it. You'll need to use one of the following methods:

iOS/visionOS:
- Finder (macOS): Connect your device via USB. In Finder, select your device from the sidebar and drag the .ipa onto the general information window.
macOS:
- Simply download and unzip the artifact, then run the .app or installer. Note that you may need to right-click and select "Open" to bypass security warnings if it's not notarized yet.

Deploying to TestFlight

Sideloading is great for quick tests, but for beta testing with your team (or the world), TestFlight is the way to go. This works for iOS, tvOS, visionOS, and macOS apps.

1. Create a Testing Group

First, organize your testers in App Store Connect.

Navigate to App Store Connect > My Apps > Select your App > TestFlight.
Under Internal Testing, click the (+) button to create a group (e.g., "Internal Testers").
Add your team members to this group.

2. Update the Workflow

Now we just need to tweak our workflow to tell it to upload to App Store Connect instead of just signing for development. Change the export-option to app-store-connect and specify your test group:

      - uses: buildalon/unity-xcode-builder@v1
        with:
          project-path: ${{ github.workspace }}/Builds/iOS/**/*.xcodeproj
          export-option: app-store-connect
          # ... credentials ...
          # Automatically invite this group when the build processes
          test-groups: "Internal Testers"

Once the build finishes, Buildalon will upload the archive. Apple usually takes a few minutes to process it. Once that's done, your "Internal Testers" will get an email, and they can start testing immediately.

3. Download & Play

Your testers just need to grab the TestFlight app from the App Store. Once they accept the invite, your game will appear there, ready to install.

Tip: Want to tell your testers what's new? Add the release-notes parameter to the buildalon/unity-xcode-builder step. You can even pass ${{ github.event.head_commit.message }} to automatically use your commit message!

About Buildalon

Buildalon provides verified GitHub Actions and dedicated build infrastructure to streamline Unity development. Register for Buildalon to get support with your Unity build automation needs.

Unit Testing for Unity Developers

Alon Farchy — Wed, 22 Jan 2025 16:04:02 +0000

Let's face it Unity developers — you write buggy code. I write buggy code. AI writes buggy code.

Many software engineers consider unit testing as the key to catching bugs early and preventing regressions. But do they work for Unity developers?

In this article, I'll share with you how we do testing at Virtual Maker. We'll learn the difference between unit tests, integration tests, and end-to-end tests, and why I think you should avoid writing the latter.

Then, we'll dive into some code and learn how to write tests using the NUnit framework in Unity. To top it off, we'll learn how to run tests from the command line and using GitHub Actions to truly automate the testing process.

Unit Testing at Virtual Maker
Types of Tests
Writing Tests in Unity using NUnit
Edit Mode Tests
Play Mode Tests
Run Tests from the Command Line
Running Tests in Automation using GitHub Actions
Summary

Unit Testing at Virtual Maker

At Virtual Maker, we use unit testing to extensively test our Unity plugins and ensure they work in a variety of scenarios.

In Flexalon 3D Layouts, we test each layout component with different configurations and edge cases. Similarly, in Proxima Inspector, we test the protocol between Unity and the browser, to ensure that the right data is sent for each type of component and gameObject.

On top of ensuring that all edge cases work correctly, unit tests help us to prevent regressions. Whenever we fix bugs or add new features, we invariably introduce some new bugs.

To catch these, we set up our tests to run automatically whenever we make a pull request in GitHub, so any of these bugs are caught well before a change makes it in into a release.

But not all tests are created equal. In my past job at Microsoft, we spent a heck of a lot of time writing tests that didn't catch any bugs. Worse, we wrote tests that were so brittle that we spent more time investigating issues and fixing the tests than actually working on the product.

So what makes one test good and another test bad?

Types of Tests

Often, what separates a good test from a bad test is a matter of scope. Ask yourself the question: how many components need to work correctly for a test to pass?

Unit Tests: Test a single method or class in isolation.
Integration Tests: Test the multiple components work together correctly.
End-to-end Tests: Test that game features work as expected from as close to a player's perspective as possible.

Unit Testing

Advocates for unit testing argue that tests should be as small as possible — test a single method or class in isolation. These tests are quick to run and easy to debug. For complex functions, especially math functions, they can also provide a lot of value.

For example, Proxima Inspector has a CircularList class that stores Unity logs so that you can see past logs after connecting the inspector. This class was tricky to get right, so we write some unit tests.

[Test]
public void EnumerableWrap()
{
    var list = new CircularList<int>(2); // Constructs a circular list with a size of 2
    list.Add(1);
    list.Add(2);
    list.Add(3);
    Assert.AreEqual(3, list.ItemsAdded);
    var items = list.ToList();
    Assert.AreEqual(2, items.Count);
    Assert.AreEqual(2, items[0]);
    Assert.AreEqual(3, items[1]);
}

This test checks that the CircularList class wraps around when it reaches its capacity. It adds three items to the list, then checks that the list only contains the last two items.

Integration Testing

Scoped unit testing is great for checking the behavior of complex functions and classes. But often, it's not enough. In Flexalon, most of the difficult bugs come from the interactions between multiple Flexalon components.

In this case, we should think of how to test the Flexalon package as an isolated component.

How can we test this scenario? The test needs to:

Create a scene.
Add some gameObjects with Flexalon components.
Have Flexalon run its layout.

Note 1: You can can still use a "unit testing framework" to write integration tests, or even end-to-end tests. Don't look at me, I don't make the rules.

Note 2: "Integration testing" can also refer to the integration between modules, processes, or even distributed computers. Here, I'm using the term to refer to the scope of the test as bigger than a single class or method. Think of testing a whole package or library.

Here's an example of a real test from Flexalon:

[Test]
public void FillChild()
{
    // Create and configure a Flexible Layout
    var flex = CreateFlex();
    var flexObj = flex.GetComponent<FlexalonObject>();
    flexObj.Width = 3;

    // Add a child to the layout
    var child = CreateCube(flex.transform);
    var obj = child.AddComponent<FlexalonObject>();
    obj.WidthOfParent = 0.5f;

    // Add another child to the layout
    var child2 = CreateCube(flex.transform);

    // Update the layout
    Update();

    // Check the results
    AssertTransform(flex.transform);
    AssertTransform(child.transform, new Vector3(-0.5f, 0, 0));
    AssertTransform(child2.transform, new Vector3(0.5f, 0, 0));
}

Since there are many such tests, we wrote helper methods for common functionality: create Flexalon components, update the layout, and check the results.

Importantly, these tests run in edit mode. We don't need to play the game to run these tests, and we don't have to perform any asynchronous actions. Flexalon was designed this way so that it would be easy to test. By calling Update(), we force Flexalon to immediately process all layout updates, even though it would normally wait for the next frame.

This is key: write your components so they are easy to test in isolation. If your tests are not fast and reliable, they will quickly lose their value. This brings us to...

End-to-end Testing

In end-to-end testing, we try to test the product as a user would use it. Typically, this involves setting up some input simulation so that the test can act as a player, play the game, and then check the results.

With end-to-end tests, you can be sure that the product is really working as expected. By bother testing every edge of every component in isolation when you can just test the real player experience?

Or, so the thinking goes.

In reality, end-to-end are often slow, brittle, and hard to maintain.

Let's use a simple example. Suppose you want to test that the player can change the volume. First, the player has to open the main menu, then drag the volume slider. What are the problems?

Slow: If an animation to open the main menu takes 2 seconds, then the test needs to wait 2 seconds. Multiply this by the number of tests that have to open the main menu.
Brittle: What if the animation takes a little longer to run because the test computer is slow? We aren't trying to test performance here, yet the test will fail. What if the volume slider position changes depending on screen size? Eventually, you find yourself bending over backwards trying to stabilize the testing environment.
Hard to maintain: Suppose a designer decides to change the main menu animation to 3 seconds. Now all the tests that depend on the main menu need to be updated to wait for 3 seconds instead of 2.

Clever developers will try to circumvent these problems by adding features that make the tests faster and more reliably. For example, instead of waiting 2 seconds for an animation to play, we can add a special open-main-menu-completed event to the game that the test can wait for. Then, crank up the time scale to 10x speed so that the all animations complete in 0.2 seconds.

While the intentions here are good, the fallacy is that now developers are spending more time debugging tests and writing test infrastructure instead of improving the product. In one of my past projects, we actually spent more time debugging issues with the tests than we did with the product.

Ok, ok, but should I EVER write end-to-end tests?

Probably not.

Instead, design your app so that the parts that are difficult to get right can be tested in isolation. Leave the end-to-end testing to the humans. Or sentient AI, as the case may be.

Writing Tests in Unity using NUnit

Unity has a built-in unit testing framework called NUnit. To get started, you just need to install the NUnit package from the Unity Package Manager.

Go to Window > Package Manager.
In the Package Manager window, select Unity Registry from the dropdown.
Search for NUnit and click Install on the NUnit package.

Edit Mode vs Play Mode Tests

In Unity, there are two type sof tests: edit mode tests and play mode tests.

Edit Mode Tests: These tests run within the Unity Editor. They are ideal for both unit tests and integration tests. Wherever possible, you should use edit mode tests.
Play Mode Tests: These tests can run in the Unit Editor in play mode or in a standalone player. These types of tests should be used as a last resort since they are slower and less reliable. Whenever possible, it is better to update your components to support edit mode tests than to write play mode tests.

Edit Mode Tests

For demonstration, we'll use this simple SimpleCircleLayout component that arranges its children in a circle around its center.

This is a super simplified version of the FlexalonCircleLayout component, which has tests that are similar to the ones we'll write here.

using UnityEngine;

public class SimpleCircleLayout : MonoBehaviour
{
    public float Radius = 2;

    public void LayoutChildren()
    {
        float angle = 0;

        foreach (Transform child in transform)
        {
            float x = Radius * Mathf.Cos(angle);
            float y = Radius * Mathf.Sin(angle);
            child.position = transform.position + new Vector3(x, y, 0);
            angle += 2 * Mathf.PI / transform.childCount;
        }
    }
}

Create a Assembly Definition for Edit Mode Tests

Before we can write tests, we need to create a special assembly where our tests will live.

Open Window > General > Test Runner.
If you don't have any tests in your project you'll see this:

Click Create EditMode Test Assembly Folder. This will create a new "Tests" folder with an assembly definition file. You can rename this however you like.
In order to test your code, it needs to be in its own assembly definition file. If your script is in your main project, right click the Assets folder in the Project window and select Create > Assembly Definition.

Drag your assembly definition into the references of the test assembly definition.

Here's the final test assembly definition for Flexalon:

Write your Test Class

Now that we have our assembly set up, we can start writing tests. Create a new file called SimpleCircleLayoutTests.cs in your test folder, next to the assembly definition file.

using NUnit.Framework;
using UnityEngine;

[TestFixture]
public class SimpleCircleLayoutTests
{
    [Test]
    public void TestLayoutChildren()
    {
        var layout = new GameObject().AddComponent<SimpleCircleLayout>();
        layout.Radius = 2;

        var child1 = new GameObject().transform;
        var child2 = new GameObject().transform;
        var child3 = new GameObject().transform;

        child1.SetParent(layout.transform);
        child2.SetParent(layout.transform);
        child3.SetParent(layout.transform);

        layout.LayoutChildren();

        TestUtil.AssertVector3Equal(new Vector3(2, 0, 0), child1.position);
        TestUtil.AssertVector3Equal(new Vector3(-1, 1.73f, 0), child2.position);
        TestUtil.AssertVector3Equal(new Vector3(-1, -1.73f, 0), child3.position);
    }
}

In this first test, we create a SimpleCircleLayout component and add three child objects to it. We then call the LayoutChildren method and assert that the children are positioned correctly in a circle around the center. Finally, we use the Assert class to check if the positions are as expected.

You can add other tests by creating new methods with the [Test] attribute. Each test method should be self-contained and test a specific aspect of the component.

Running Edit Mode Tests

To run your edit mode tests, go to the Unity Test Runner window (Window > General > Test Runner) and click the Run All button. The test results will be displayed in the Test Runner window, showing you which tests passed and which failed.

You'll notice, oddly, that the tests fail with the message:

TestLayoutChildren (0.012s)
---
Expected: (-1.00, 1.73, 0.00)
  But was:  (-1.00, 1.73, 0.00)
---

But why?

Improving equality tests for Vector3 and Quaternion

Unity's Vector3 and Quaternion types are floating-point values, which can lead to precision issues. The actual Y value is not exactly 1.73, Unity is just printing out the first 2 digits after the decimal.

To address this, you can use a helper class to checks if the difference between two values is within a certain tolerance (0.01).

using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools.Utils;

public class TestUtil
{
    private static Vector3EqualityComparer vector3Comparer = new(0.01f);
    private static QuaternionEqualityComparer quaternionComparer = new(0.01f);

    public static void AssertVector3Equal(Vector3 expected, Vector3 actual)
    {
        Assert.That(actual, Is.EqualTo(expected).Using(vector3Comparer), "Vectors are Equal");
    }

    public static void AssertQuaternionEqual(Quaternion expected, Quaternion actual)
    {
        Assert.That(actual, Is.EqualTo(expected).Using(quaternionComparer), "Quaternions are Equal");
    }
}

Now if we replace the Assert.AreEqual calls with TestUtil.AssertVector3Equal, the tests will pass.

Setup and Teardown

In some cases, you may find it convenient to perform common setup and teardown steps before and after each test. You can use the [SetUp] and [TearDown] attributes to mark methods that run before and after each test, respectively.

For example, suppose we want to test the circle layout with different numbers of children.

using NUnit.Framework;
using UnityEngine;

[TestFixture]
public class SimpleCircleLayoutTests
{
    private SimpleCircleLayout _layout;

    [SetUp]
    public void Setup()
    {
        _layout = new GameObject().AddComponent<SimpleCircleLayout>();
        _layout.Radius = 2;
    }

    [TearDown]
    public void Teardown()
    {
        GameObject.DestroyImmediate(_layout.gameObject);
    }

    [Test]
    public void TestOneChild()
    {
        var child = new GameObject().transform;
        child.SetParent(_layout.transform);

        _layout.LayoutChildren();

        TestUtil.AssertVector3Equal(new Vector3(2, 0, 0), child.position);
    }

    [Test]
    public void TestTwoChildren()
    {
        var child1 = new GameObject().transform;
        var child2 = new GameObject().transform;

        child1.SetParent(_layout.transform);
        child2.SetParent(_layout.transform);

        _layout.LayoutChildren();

        TestUtil.AssertVector3Equal(new Vector3(2, 0, 0), child1.position);
        TestUtil.AssertVector3Equal(new Vector3(-2, 0, 0), child2.position);
    }
}

In this example, the Setup method creates a new SimpleCircleLayout component before each test, and the Teardown method destroys it after each test. This ensures that each test starts with a clean slate and doesn't interfere with other tests.

Test Attributes

Unity's test framework provides several other attributes that you can use to organize and manage your tests effectively:

[TestFixture]: Indicates a class that contains tests.
[Test]: Marks a method as a test.
[SetUp]: Identifies a method that runs before each test. It's used to set up conditions required for the tests.
[TearDown]: Identifies a method that runs after each test. It's used to clean up any resources or state.
[OneTimeSetUp]: Runs once before all tests in the test class.
[OneTimeTearDown]: Runs once after all tests in the test class.
[UnityTest]: For play mode tests (read on below). This tells Unity to run the test as a coroutine.

Generally speaking, be wary of [OneTimeSetUp] and [OneTimeTearDown], as they can lead to dependencies between tests. For example, suppose we created the SimpleCircleLayout in [OneTimeSetUp] instead of [SetUp]. The same layout would be shared between all tests. If one test adds children and doesn't clean up after itself, the next test would run with extra children, leading to unexpected failure.

Play Mode Tests

Play mode tests can run in the Unity Editor in play mode or in a standalone player. This can make play mode tests slow and brittle.

But there are some scenarios where play mode tests makes sense because the behavior you want to takes multiple frames to complete.

For example, Flexalon has a FlexalonInteractable component that allows the player to click and drag an object. We need to test that if the player clicks on the interactable and drags it out of a layout, then the object ends up in the correct position and the layout updates correctly. Here's a real example:

<video controls="" loop="">
    <source src="/images/blog/flexalon-grab-vr.mp4" type="video/mp4">
</source></video>
<p>Testing the VR grab interactables in Flexalon 3D Layouts</p>

[UnityTest]
public IEnumerator DraggableRemove()
{
    var dragTarget = CreateDragTarget();
    var interactable1 = CreateInteractable(dragTarget.transform);
    var interactable2 = CreateInteractable(dragTarget.transform);

    yield return MoveFromTo(new Vector3(0.5f, 0, 0), new Vector3(2.5f, 0, 0));

    Assert.AreEqual(1, dragTarget.transform.childCount);
    Assert.IsTrue(interactable1.transform == dragTarget.transform.GetChild(0));
}

Indeed, these tests are the slowest and most brittle tests in Flexalon. In particular, the MoveFromTo helper function took some quite some time to get right. But we feel these tests are worth the tradeoff because they test a critical part of the product, and there are many possible edge cases.

Example that Requires Play Mode Tests

To demonstrate play mode tests, let's add a RotateOnce component. The component will rotate a gameObject once and only once around the Z-axis over a duration.

using UnityEngine;

public class RotateOnce : MonoBehaviour
{
    public float Duration = 3.0f;

    private float _startTime;

    private void OnEnable()
    {
        _startTime = Time.time;
    }

    private void Update()
    {
        float t = (Time.time - _startTime) / Duration;
        transform.rotation = Quaternion.Euler(0, 0, Mathf.Lerp(0, 360, t));
    }
}

Create a Assembly Definition for Play Mode Tests

Play mode tests need to be in a separate assembly from edit mode tests, since they cannot reference the UnityEditor namespace. Follow the same steps as for edit mode tests, but this time click "Play Mode".

Play Mode Test Basics

Now that we have our assembly set up, we can start writing play mode tests. Create a new file called RotateOnceTests.cs in your test folder, next to the assembly definition file.

using NUnit.Framework;
using UnityEngine;

[TestFixture]
public class RotateOnceTests
{
    [UnityTest]
    public IEnumerator TestRotateOnce()
    {
        var rotateOnce = new GameObject().AddComponent<RotateOnce>();
        rotateOnce.Duration = 3.0f;

        yield return new WaitForSeconds(1f);

        TestUtil.AssertQuaternionEqual(Quaternion.Euler(0, 0, 120), rotateOnce.transform.rotation);

        yield return new WaitForSeconds(1f);

        TestUtil.AssertQuaternionEqual(Quaternion.Euler(0, 0, 240), rotateOnce.transform.rotation);

        yield return new WaitForSeconds(1f);

        TestUtil.AssertQuaternionEqual(Quaternion.Euler(0, 0, 360), rotateOnce.transform.rotation);

        yield return new WaitForSeconds(1f);

        // Make sure it only rotates once!
        TestUtil.AssertQuaternionEqual(Quaternion.Euler(0, 0, 360), rotateOnce.transform.rotation);
    }
}

In this test, we create a RotateOnce component that will rotate once over 3 seconds, and then check the rotation at different points in time.

For this test to work, we need to use the [UnityTest] attribute instead of [Test] and change the return type to IEnumerator. This treats the method as a coroutine, and you can use yield return to perform asynchronous operations. Learn more about coroutines in Unity.

Running Play Mode Tests

To run your play mode tests, go to the Unity Test Runner window (Window > General > Test Runner) and select PlayMode from the dropdown. Click the Run All button to run the tests. The test results will be displayed in the Test Runner window, showing you which tests passed and which failed.

Tip: If you add Debug.Log statements to your test, they'll appear in the test results. This can be helpful for debugging failing tests.

Run Tests from the Command Line

Running tests manually is fine for small projects, but as your project grows, you'll want to automate your tests to catch issues early and ensure consistent quality. Unity provides command line options to run tests, allowing you to integrate them into your build pipeline or continuous integration (CI) system.

To run your tests from the command line, use the -runTests argument followed by the -testPlatform to specify where to run the tests (EditMode or PlayMode).

Unity.exe -batchmode -nographics -runTests -projectPath "path/to/your/project" -testPlatform EditMode

Note: Do not pass the -quit flag to the command line, as it will quit Unity before any tests run. NUnit will automatically quit Unity after the tests are done.

There are additional options that you can use to filter which tests to run. See the full list of command line arguments.

Analyzing Test Results

The command will generate a file named something like TestResults-638683971208353675.xml in your project root directory, which you can inspect to see the results of your test. For example:

<test-case id="1305" name="Collider2DFixedAndComponent" fullname="FlexalonAdapterTests.Collider2DFixedAndComponent" methodname="Collider2DFixedAndComponent" classname="FlexalonAdapterTests" runstate="Runnable" seed="4201476" result="Passed" start-time="2024-11-26 03:42:24Z" end-time="2024-11-26 03:42:24Z" duration="0.001536" asserts="0">

Here we see the result of test FlexalonAdapterTests.Collider2DFixedAndComponent with result="Passed".

Running Tests in Automation using GitHub Actions

Now that we know how to run tests from the command line, you can easily add it to any continuous integrate (CI) pipeline that you have set up.

If you're using GitHub actions, we wrote the article Automating Unity Builds with GitHub Actions that will help you get started.

You can then update your workflow file to run the tests. We recommend injecting this after the Project Validation step:

name: Run Edit Mode Tests
using: buildalon/unity-action@v1
  with:
    build-target: ${{ matrix.build-target }}
    args: -runTests -batchmode -testPlatform EditMode -testResults "${{ env.UNITY_PROJECT_PATH }}/Logs/EditMode-test-results.xml"
    log-name: EditMode-Tests

You also need to update the actions/upload-artifacts step to add the test results to the uploaded artifacts:

- uses: actions/upload-artifact@v4
  # ...
  with:
    # ...
    path: |
      ${{ github.workspace }}/**/*.xml # <- ADD THIS LINE
      # ...

Summary

The Unity NUnit package provides a powerful way to write tests to prevent bugs in your project. We covered the differences between unit testing, integration testing, and end-to-end testing, and when it's appropriate to use each.

We also learned how to write edit mode tests and play mode tests, and how to run them from the command line or in automation using GitHub Actions.

Armed with this knowledge, I expect bug free code from you from now on.

Go forth and test!

Automating Unity Builds with GitHub Actions

Alon Farchy — Thu, 09 Jan 2025 15:40:15 +0000

When working on a Unity project, you may find yourself making many builds to play test your changes. Since Unity locks the editor while building, this can leave you twiddling your thumbs for what seems like hours. By automating your builds, you can get your your time back, and at the same time streamline the development process for your team.

In this guide, we'll walk through how to use GitHub Actions to automate Unity builds. We’ll learn step by step how to create a GitHub workflow, add the necessary secrets, and choose an appropriate build machine.

What is Build Automation (CI/CD)?

Continuous Integration (CI) and Continuous Deployment (CD) are practices that automate the process of building, testing, and deploying your project. CI/CD pipelines can be set up to run automatically whenever you push changes to your repository, ensuring you have a build ready to test at any time.

What are GitHub Actions?

GitHub Actions is a feature of GitHub that allows you run automated steps when changes happen in your GitHub repository. You can create custom workflows that run on specific triggers, such as pushing code to a repository or opening a pull request. These workflows can be used to build, test, and deploy your code automatically.

If you're new to Git and GitHub, learn how to setup Git for Unity in our Comprehensive Guide to Version Control for Game Devs.

What is Buildalon?

Buildalon turns GitHub Actions into a powerful CI/CD tool for Unity developers. It provides a set of free open-source GitHub Actions that we'll need to build a Unity project, and (optionally) build machines that support fast incremental builds.

Buildalon Quick Start (optional)

In the rest of this article we'll cover the nitty-gritty details of writing GitHub Actions workflow to automate Unity builds.

However, you can also use the Buildalon Quick Start to generate a workflow. This is the fastest way to get started, and you can come back to learn the details later.

Creating Your Build Workflow

Step 1: Create a Workflow File

To get started, you need to create a workflow file in your repository. This file will define the steps that GitHub Actions will take to build your Unity project. Create the file unity-build.yml and put in a directory named .github/workflows in your repository.

Step 2: Add Triggers

Triggers are events that tell GitHub to start a workflow. Triggers help streamline development by automatically initiating builds, tests, or deployments whenever key events occur, reducing the need for manual intervention.

These example triggers will run the workflow on every push to the main branch and on every pull request to any branch:

on:
  push:
    branches:
      - main

  pull_request:
    branches:
      - '*'

Learn more about the different triggers available.

Step 3: Add a job

A job is a set of steps that run sequentially on the same build machine. Each job can run on a different machine, allowing you to parallelize your workflow and speed up the build process.

Example: Define the 'build' Job

jobs:
  build:
    env:
      UNITY_PROJECT_PATH: ''
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [buildalon-windows]
        include:
          - os: buildalon-windows
            build-target: StandaloneWindows64
            build-args: ''

The 'env' section defines environment variables that can be used in the job, and we'll need to declare the UNITY_PROJECT_PATH variable for later steps.

The 'runs-on' section specifies which build machines should be used, based on a runner label. Here we use a matrix strategy to define different operating systems and build targets. You can add more build targets in the future and run them in in parallel.

The buildalon-windows label tells GitHub to run this workflow on a Buildalon Windows runner. You can also use buildalon-macos or buildalon-ubuntu for macOS and Linux builds, respectively. Buildalon runners support incremental builds, which will speed up your builds considerably.

If you prefer to use GitHub runners, change the label to windows-latest, macos-latest, or ubuntu-latest. For advanced users, you can also set up your own self-hosted runners.

The StandaloneWindows64 build target specifies that we want to build a 64-bit Windows standalone application. You can add more build targets by including them in the matrix, and these should match the names of the available Unity build targets.

You can use build-args to pass additional arguments to Unity when it is run from the command line.

Step 4: Add Steps

The minimum steps we need to build a Unity project are:

Checkout the repository - actions/checkout
Install Unity - buildalon/unity-setup
Activate the Unity license - buildalon/activate-unity-license
Add the Buildalon Unity Plugin - com.virtualmaker.buildalon
Build the project - buildalon/unity-action
Upload the build artifacts - actions/upload-artifact

Below is an example set of steps for making a Windows desktop build. These steps were generated using Buildalon Quick Start.

Note: Since the set of steps is a bit different for each platform, we recommend using Buildalon Quick Start to generate the steps for your specific platform. For example, an additional step — buildalon/unity-xcode-builder — is required to run XCode to build an iOS project.

    steps:
      - uses: actions/checkout@v6
        with:
          clean: ${{ github.event.inputs.clean == 'true' }}
          lfs: true
          submodules: 'recursive'
      - uses: buildalon/unity-setup@v2
        with:
          build-targets: '${{ matrix.build-target }}'
      - uses: buildalon/activate-unity-license@v2
        with:
          license: 'Personal'
          username: '${{ secrets.UNITY_USERNAME }}'
          password: '${{ secrets.UNITY_PASSWORD }}'
      - name: Add Build Pipeline Package
        working-directory: ${{ env.UNITY_PROJECT_PATH }}
        run: |
          npm install -g openupm-cli
          openupm add com.virtualmaker.buildalon
      - uses: buildalon/unity-action@v3
        name: Project Validation
        with:
          log-name: 'project-validation'
          build-target: '${{ matrix.build-target }}'
          args: '-quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject'
      - uses: buildalon/unity-action@v3
        name: '${{ matrix.build-target }}-Build'
        with:
          log-name: '${{ matrix.build-target }}-Build'
          build-target: '${{ matrix.build-target }}'
          args: '-quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild${{ matrix.build-args }}'
      - uses: actions/upload-artifact@v6
        id: upload-artifact
        name: 'Upload ${{ matrix.build-target }} Artifacts'
        if: success() || failure()
        with:
          compression-level: 0
          retention-days: 1
          name: '${{ github.run_number }}.${{ github.run_attempt }}-${{ matrix.os }}-${{ matrix.build-target }}-Artifacts'
          path: |
            ${{ github.workspace }}/**/*.log
            ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/**/*.exe
            ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/**/*.dll
            ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/**/*_Data
            ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/MonoBleedingEdge/
      - name: Clean Artifacts
        if: always()
        shell: pwsh
        run: |
          # Clean Logs
          Get-ChildItem -Path "${{ env.UNITY_PROJECT_PATH }}" -File -Filter "*.log" -Recurse | Remove-Item -Force

          $artifacts = "${{ env.UNITY_PROJECT_PATH }}/Builds"
          Write-Host "::debug::Build artifacts path: $artifacts"

          if (Test-Path -Path $artifacts) {
            try {
              Remove-Item $artifacts -Recurse -Force
            } catch {
              Write-Warning "Failed to delete artifacts folder file: $_"
            }
          } else {
            Write-Host "::debug::Artifacts folder not found."
          }

Step 5: Add Secrets

To activate the Unity license, the build machine needs access to your Unity username and password. You should never hardcode these values in your workflow file, as they can be exposed to the public. Instead, you can use GitHub Secrets to securely store sensitive information.

Go to your repository on GitHub, click on Settings > Secrets & Variables > Actions and add the following secrets:

UNITY_USERNAME: Your Unity username, usually your email.
UNITY_PASSWORD: Your Unity password.

For Unity Pro:

If you're using Unity Pro, you also need to add the UNITY_SERIAL secret with your serial key. Then go back to your workflow file and update the activate-unity-license step to use the secrets:

- uses: buildalon/activate-unity-license@v1
  with:
    license: 'Professional'
    username: '${{ secrets.UNITY_USERNAME }}'
    password: '${{ secrets.UNITY_PASSWORD }}'
    serial: '${{ secrets.UNITY_SERIAL }}'

Step 6: Install the Buildalon GitHub App

To use Buildalon runners, you need to install the Buildalon GitHub App on your repository. This app gives you access to Buildalon runners to run your workflows.

Install the Buildalon App

Buildalon runners are optimized for Unity builds and enable incremental builds, which will speed up your build times considerably.

If you prefer to use GitHub's runners, you can skip this step, but make sure you update the runner label in your workflow file (for example, windows-latest).

Step 7: Push Your Changes to Start a Build

Once you've added the workflow file and secrets to your repository, push your changes to GitHub. If your trigger conditions are met, GitHub Actions will automatically start the workflow and build your Unity project. You can find the status of the workflow in the Actions tab of your repository.

Step 8: Monitor Your Build

Once the workflow is running, you can monitor its progress in the Actions tab of your repository. You can view the logs of each step to see what's happening during the build process.

If there are errors, you can usually find them in the Summary page. Fix the errors in your project and push the changes to trigger a new build.

For more help with common errors, take a look at the Buildalon troubleshooting page.

Step 9: Retrieve Your Build Artifacts

Once the build is complete, you can download the build artifacts from the bottom of the Summary page. These artifacts will contain the build files generated by Unity, such as the executable and data files.

Next Steps

🎉 Congratulations, you now have automated builds! 🎉

Here are some ideas on how to augment your new workflow:

Add more build targets to the matrix to build for different platforms.
Run unit tests automatically.
Deploy your builds to an app store.
Add webhooks to notify your team when a build is complete.
Create a branch protection policy to ensure that all code changes are tested before merging.

DEV Community: Alon Farchy

Deploying Unity Builds to Google Play Store with Buildalon

Table of Contents

Prerequisites

Setup Overview

Setting up Google Play Console

Configuring Google Cloud Access

1. Enable the Google Play Android Developer API

2. Create a Service Account

3. Setup Workload Identity Federation

Handling the Keystore

Method 1: Base64 Encoding (Recommended)

Method 2: Repo Storage

Updating the Build Pipeline

Key Steps Explained

Deploying to Internal Testing

Common Gotchas

Installing the Internal App and Inviting Testers

Invite Internal Testers

How Testers Install the Internal Version

About Buildalon

Automating Unity Builds for Meta Quest

Table of Contents

Setting up the Meta Developer Portal

Create Your App

Get Your Credentials

Create a Release Channel

Configure GitHub Secrets for Meta

Configure GitHub Secrets for Keystores and Signing

What is a Keystore?

Creating a Keystore

Keystore Security

Update Your Build Workflow

Key Changes:

Installing the Build on Your Headset

About Buildalon

Automating Unity Builds to iOS, macOS, and visionOS

Automating Unity Builds to iOS, macOS, and visionOS

Table of Contents

Prerequisites

Setup Overview

Creating the App on Apple's Portal

Setting up App Store Connect Authentication

1. Generate an API Key

2. Base64 Encode the Key

3. Add Secrets to GitHub

Generating a Build for Sideloading

1. The Workflow

2. Grab the Artifact

3. Installing the Build

Deploying to TestFlight

1. Create a Testing Group

2. Update the Workflow

3. Download & Play

About Buildalon

Unit Testing for Unity Developers

Table of Contents

Unit Testing at Virtual Maker

Types of Tests

Unit Testing

Integration Testing

End-to-end Testing

Ok, ok, but should I EVER write end-to-end tests?

Writing Tests in Unity using NUnit

Edit Mode vs Play Mode Tests

Edit Mode Tests

Create a Assembly Definition for Edit Mode Tests

Write your Test Class

Running Edit Mode Tests

Improving equality tests for Vector3 and Quaternion

Setup and Teardown

Test Attributes

Play Mode Tests

Example that Requires Play Mode Tests

Create a Assembly Definition for Play Mode Tests

Play Mode Test Basics

Running Play Mode Tests

Run Tests from the Command Line

Analyzing Test Results

Running Tests in Automation using GitHub Actions