DEV Community: Alon Farchy

Git and Unity: A Comprehensive Guide to Version Control for Game Devs

Alon Farchy — Fri, 15 May 2026 22:52:05 +0000

I have been using Git for version control for over 15 years. It's been my constant companion on tiny personal projects, 20-person Unity projects, and even the massive Windows operating system. Git has become the de facto standard for the software industry, and it's growing in popularity for Unity game development.

This article was originally posted to virtualmaker.dev

Git is actually easy to learn if you start from the fundamentals. In this guide, we'll begin with the basics of setting up Git for Unity to track versions of your project. Then, we'll move on to more advanced topics like backing up your project to GitHub, collaborating with a team, and sharing code and assets between multiple projects.

Quick Summary

If you're short on time, here’s the high-level flow for Unity version control:

Initialize a Git repository in your Unity project.
Add a Unity-specific .gitignore so you don’t commit generated files.
Use Git LFS for large assets (textures, audio, video, models).
Commit early and push to GitHub for backup and collaboration.

Prerequisites

Before you start, make sure you have:

A Unity project that builds locally.
Git installed (CLI tools or a Git client).
A GitHub account if you want remote backups or collaboration.

Quick Summary
Prerequisites
Why You Need Version Control for Unity
What is Git?
What is a .gitignore?
How to Initialize a Git Repository for Your Unity Project
Using Git LFS with Unity To Track Large Assets
Making Your First Commit
Useful Git Commands for Unity Developers
Commit Early, Commit Often
Branching and Merging
Asset Conflicts and Merging
Git Clients: UI for Git!
Git on the Web: GitHub for Unity Developers
Pushing your Unity Project to GitHub
Working with a Team: GitHub Organizations
Creating Your First Pull Request on GitHub
Sharing Code and Assets Between Projects: Submodules vs Unity Packages
Git on a Team: Branching Strategies for Unity
Automated Unity Builds and CI/CD with GitHub Actions

Why You Need Version Control for Unity

Timmy the Clever Game Developer

Meet Timmy, a talented and passionate game developer. Like many before him, Timmy started his career by working on small projects, handling everything from code to art. Timmy had a clever way of tracking changes to his project. Whenever he made significant changes, he would create a new version of the file, appending a systematic version number to end of the filename. It worked great – GameScene_v0.0.1.unity, GameScene_v0.0.2.unity, and so on.

But as his projects grew in complexity, so did his file naming conventions. Soon, his project folder was littered with files GameScene_v3.6.7_FINAL.unity, GameScene_v3.6.7_FINAL_b.unity, and GameScene_v3.6.7_REALLYFINAL.unity. Finding the right file became a game in itself. Timmy's team was not too happy either, unable to understand which version of Timmy's files they should use.

There must be a better way, Timmy thought.

Timmy Discovers Source Control

One day, Timmy decided enough was enough. He read an interesting blog post which introduced him to the world of version control systems (VCS). Intrigued, Timmy started learning about Git, a popular and powerful VCS.

The more Timmy learned about Git, the more he realized how it could revolutionize his workflow. Instead of manually renaming files and risking data loss, Git could track every change automatically. He could create branches for new features, merge them seamlessly, and revert to previous versions effortlessly. Collaboration would become straightforward, with each team member working on their own branch without conflict.

What is Git?

Git is a distributed version control system (VCS) that allows developers to track changes in their code, collaborate with others, and manage their projects efficiently.

Git was initially created by Linus Torvalds, the creator of the Linux operating system, in 2005. He developed Git to manage the Linux kernel development, and it has since become one of the most widely used version control systems in the world.

Git has been used for solo Unity projects and for AAA games. At Virtual Maker, we use Git for all of our projects.

Basic Concepts

Learning all the concepts in Git can take a bit of time. We'll start with the core concepts that are most important to understanding what you're doing.

Repository / Repo

All of your project files and the entire history of their changes are kept in a repo. A repo can be stored locally on your computer or remotely on a service like GitHub or GitLab.

Commit

Commits are the units of your Git history. Each time you make changes, you bundle them into a commit. Git stores commits in a directed graph where each commit points to the previous commit.

Branch

A branch is just a named location in your Git history. You can create branches to work on different bugs and features independently, then "merge" those branches back together when you're done. The default branch is often called main.

How to Initialize a Git Repository for Your Unity Project

To get started, you need to install Git from one of these links:

In this guide, we’ll illustrate how to use Git with the command line. This is the best way to understand how Git works. Once you've mastered the basics, you can use Git Clients like Fork and GitHub Desktop that offer a graphical interface (if you prefer).

Let's get started.

Choose a Unity project or create a new one. Then, open your terminal or command prompt and navigate to your Unity project directory.

> cd path/to/my/unity/project

Initialize the repository by using the git init command:

> git init
Initialized empty Git repository in /Users/vm/repos/GitTestProject/.git/

This command creates a new subdirectory named .git that contains all of your necessary repository files.

Now, use git status to see what Git sees.

> git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        Assets/
        GitTestProject.sln
        Library/
        Logs/
        Packages/
        ProjectSettings/
        Unity.Services.Core.Analytics.csproj
        Unity.Services.Core.Configuration.Editor.csproj
        Unity.Services.Core.Configuration.csproj
        Unity.Services.Core.Device.csproj
        Unity.Services.Core.Editor.csproj
        Unity.Services.Core.Environments.Internal.csproj
        Unity.Services.Core.Environments.csproj
        Unity.Services.Core.Internal.csproj
        Unity.Services.Core.Networking.csproj
        Unity.Services.Core.Registration.csproj
        Unity.Services.Core.Scheduler.csproj
        Unity.Services.Core.Telemetry.csproj
        Unity.Services.Core.Threading.csproj
        Unity.Services.Core.csproj
        UnityEditor.UI.csproj
        UnityEngine.UI.csproj
        UserSettings/

nothing added to commit but untracked files present (use "git add" to track)

Git says there are no commits, so nothing is being tracked in version control. Git lists files that could be tracked but aren't as untracked files.

Before we start tracking files, we need to ensure Git doesn't track anything we don't need.

What is a .gitignore?

A .gitignore file specifies which files and directories git should ignore in a project. For Unity projects, this file is crucial because it helps avoid committing all the stuff that Unity will regenerate by itself, like the Library, Temp, and Logs folders.

Here is a template .gitignore for Unity projects. Drop it in the root folder of your repository.

Now let's check what git status says:

> git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .gitignore
        .vscode/
        Assets/
        Packages/
        ProjectSettings/

nothing added to commit but untracked files present (use "git add" to track)

Notice that Unity generates .meta files for every asset. Always commit your .meta files along with the assets themselves. If you lose them, Unity will regenerate new GUIDs and break references across scenes, prefabs, and materials.

Using Git LFS with Unity To Track Large Assets

If your project doesn't have any large files, then skip this section and come back to it later. As a rule of thumb, we consider 10 MB a "large" file, but this is up to you.

The problem with large files stems from how Git was designed. Each commit in repo contains all of the changes made since the previous commit. So, if you commit a 10 MB image, you add 10 MB to the size of your repository — forever. Even if you delete the file in the next commit, the file is still tracked in the history.

To make matters worse, each time you edit and commit a large binary file like an image or audio file, the entire file is added to your Git history. This will cause the repo size to balloon, taking much more disk space on each developer's machine than they would need without Git.

Git LFS (Large File Storage) solves this problem by only storing a pointer to the large file into the Git history. The large file itself is stored in a separate database so it doesn't take space in your repository, and only the necessary version is downloaded onto each developer's machine.

Note: Git web hosts like GitHub will limit how much LFS data you can have and will charge you to increase this limit.

To use Git LFS, each member of your team needs to install it.

Install Git LFS

Once installed, Git LFS needs to be set up for each user account using git lfs install.

> git lfs install
Updated Git hooks.
Git LFS initialized.

There are two ways to tell LFS which files to track:

Track specific files.
Pattern match with the wildcard * syntax.

Important: You need to set up LFS tracking rules before adding the large files to git. Otherwise, they won't be tracked by LFS correctly.

Tracking specific files with LFS

If you're using a web host like GitHub, it's usually best to track specific large files to avoid unnecessary LFS limits and fees.
Track a specific file with LFS using the command:

> git lfs track path/to/MyLargeFile

This command will create or modify the .gitattributes file. You can inspect and edit this file manually.

path/to/MyLargeFile filter=lfs diff=lfs merge=lfs -text

The -text at the end tells Git to treat the file as binary and skip line-ending normalization. The file checked in to Git will be a simple text pointer to the real file tracked by LFS.
The "filter", "diff", and "merge" options are how LFS hooks into Git's operations to download the real file onto your machine.

Pattern matching files with LFS

Usually, large files are of a certain type. For example, maybe you have many videos of .mov format. Track these files with LFS using the command:

> git lfs track "*.mov"

Here are some other file types you may want to track. However, keep in mind that web hosts like GitHub will charge you based on how much LFS data you use.

# Image
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.gif filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.ai filter=lfs diff=lfs merge=lfs -text
*.tif filter=lfs diff=lfs merge=lfs -text

# Audio
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text

# Video
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.mov filter=lfs diff=lfs merge=lfs -text

# 3D Object
*.FBX filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
*.blend filter=lfs diff=lfs merge=lfs -text
*.obj filter=lfs diff=lfs merge=lfs -text

# ETC
*.a filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text
*.tga filter=lfs diff=lfs merge=lfs -text
*.pdf filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.dll filter=lfs diff=lfs merge=lfs -text
*.unitypackage filter=lfs diff=lfs merge=lfs -text
*.aif filter=lfs diff=lfs merge=lfs -text
*.ttf filter=lfs diff=lfs merge=lfs -text
*.rns filter=lfs diff=lfs merge=lfs -text
*.reason filter=lfs diff=lfs merge=lfs -text
*.lxo filter=lfs diff=lfs merge=lfs -text

Now that the large files are taken care of, let's get back to making your first commit!

Making your First Commit

To make a commit takes two steps. First, we "stage" the changes using the git add command. This command can be used over and over to select which files you want to add to the commit.

The git add . command is a shorthand to stage everything in the current directory.

> git add .

Let's do a quick check to see that Git is tracking with the git status command. Your list of files may be different depending on your project setup.

> git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   .gitignore
        new file:   Assets/Scenes.meta
        new file:   Assets/Scenes/SampleScene.unity
        new file:   Assets/Scenes/SampleScene.unity.meta
        new file:   Packages/manifest.json
        new file:   Packages/packages-lock.json
        new file:   ProjectSettings/AudioManager.asset
        new file:   ProjectSettings/ClusterInputManager.asset
        new file:   ProjectSettings/DynamicsManager.asset
        new file:   ProjectSettings/EditorBuildSettings.asset
        new file:   ProjectSettings/EditorSettings.asset
        new file:   ProjectSettings/GraphicsSettings.asset
        new file:   ProjectSettings/InputManager.asset
        new file:   ProjectSettings/MemorySettings.asset
        new file:   ProjectSettings/NavMeshAreas.asset
        new file:   ProjectSettings/PackageManagerSettings.asset
        new file:   ProjectSettings/Packages/com.unity.testtools.codecoverage/Settings.json
        new file:   ProjectSettings/Physics2DSettings.asset
        new file:   ProjectSettings/PresetManager.asset
        new file:   ProjectSettings/ProjectSettings.asset
        new file:   ProjectSettings/ProjectVersion.txt
        new file:   ProjectSettings/QualitySettings.asset
        new file:   ProjectSettings/TagManager.asset
        new file:   ProjectSettings/TimeManager.asset
        new file:   ProjectSettings/UnityConnectSettings.asset
        new file:   ProjectSettings/VFXManager.asset
        new file:   ProjectSettings/VersionControlSettings.asset
        new file:   ProjectSettings/XRSettings.asset
        new file:   ProjectSettings/boot.config

Now we can use the git commit command to create a new commit with a meaningful message:

> git commit -m "Initial commit of my Unity project"

[main (root-commit) e1c03d9] Initial commit of my Unity project
 29 files changed, 2717 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Assets/Scenes.meta
 create mode 100644 Assets/Scenes/SampleScene.unity
 create mode 100644 Assets/Scenes/SampleScene.unity.meta
 create mode 100644 Packages/manifest.json
 create mode 100644 Packages/packages-lock.json
 create mode 100644 ProjectSettings/AudioManager.asset
 create mode 100644 ProjectSettings/ClusterInputManager.asset
 create mode 100644 ProjectSettings/DynamicsManager.asset
 create mode 100644 ProjectSettings/EditorBuildSettings.asset
 create mode 100644 ProjectSettings/EditorSettings.asset
 create mode 100644 ProjectSettings/GraphicsSettings.asset
 create mode 100644 ProjectSettings/InputManager.asset
 create mode 100644 ProjectSettings/MemorySettings.asset
 create mode 100644 ProjectSettings/NavMeshAreas.asset
 create mode 100644 ProjectSettings/PackageManagerSettings.asset
 create mode 100644 ProjectSettings/Packages/com.unity.testtools.codecoverage/Settings.json
 create mode 100644 ProjectSettings/Physics2DSettings.asset
 create mode 100644 ProjectSettings/PresetManager.asset
 create mode 100644 ProjectSettings/ProjectSettings.asset
 create mode 100644 ProjectSettings/ProjectVersion.txt
 create mode 100644 ProjectSettings/QualitySettings.asset
 create mode 100644 ProjectSettings/TagManager.asset
 create mode 100644 ProjectSettings/TimeManager.asset
 create mode 100644 ProjectSettings/UnityConnectSettings.asset
 create mode 100644 ProjectSettings/VFXManager.asset
 create mode 100644 ProjectSettings/VersionControlSettings.asset
 create mode 100644 ProjectSettings/XRSettings.asset
 create mode 100644 ProjectSettings/boot.config

Pay attention to the first line that Git printed out:

[main (root-commit) e1c03d9] Initial commit of my Unity project

main is the name of the branch that Git added the commit onto. e1c03d9 are the last 7 characters of the ID of this commit. If we use the git log command, we can see the full ID and your message.

> git log
commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84 (HEAD -> main)
Author: Alon Farchy <some@email.net>
Date:   Tue Jul 16 15:34:39 2024 -0700

    Initial commit of my Unity project

Useful Git Commands for Unity Developers

Here are some useful Git commands that you might need frequently:

git status: Check the status of your working directory.
git add: Stage a file to be added to the commit.
git reset: Unstage a file so it won't be added to the commit.
git commit: Create a commit.
git revert: Create a new commit that undoes everything in a previous commit.
git log: View the commit history.
git reflog: View the history of what you did (commit, checkout, reset, etc.)
git branch: List, create, or delete branches.
git switch: Switch branches.
git restore: Update a file to specific version.
git checkout: Older command to switch branches or update a file to specific version
git merge: Merge branches.
git fetch: Download changes from your remote repository.
git pull: Do git fetch and then merge your branch with any remote changes.
git push: Upload changes made to your branch to your remote repository.

For a comprehensive list of commands and their usage, refer to the Git documentation, or consider learning with an interactive tutorial like learngitbranching.

Commit Early, Commit Often

In Git, commits are considered "cheap" because they only store file changes. Because of this, you can use Git as your personal undo system by committing frequently. Each time you make some small changes, you can make a commit and return to it later if you don't like the changes you made.

In Unity, committing often is even more relevant because it's easy to accidentally lose your undo history. For example, when you make some changes to a prefab in Unity, and then close that prefab, you'll lose the undo history for that prefab. Or, what if you're trying out some changes to a scene and Unity crashes? Goodbye undo history.

Your typical workflow should look something like this:

Do some work.
Hit the Save button in Unity!
Make a commit.

> git add <files>
> git commit -m "Description of what has changed"

Backup your commit by pushing it to your remote repo. We'll discuss remote repos in the section: Git on the Web: GitHub for Unity Developers.

> git push

Repeat.

Help, I made a boo boo!

If you make a mistake, you can use the commands in this cheatsheet to roll back to an earlier version.

# Unstage a file so it won't be committed
> git reset <path>

# Checkout the version of the file at the latest commit.
> git checkout -- <path>

# Restore the version of the file at the commit before the latest.
> git restore --source=HEAD~1 <path>

# Restore the version of a file at a particular commit
> git restore --source=<commit-id> <path>

# Create a NEW commit that undoes everything in the specified commit
> git revert <commit-id>

# Delete files which are not tracked by Git. Useful when Unity gets in a bad state.
> git clean -xfd <path>

# Move your branch to the target commit without changing your files.
> git reset <commit-id>

# Move your branch to the target commit and discard all your changes.
> git reset --hard <commit-id>

# Shows you the history of what you did (commit, checkout, reset, etc.)
> git reflog

Branching and Merging

Often, you and your team will be working on multiple things at once. This is where branching comes handy. In Git, you are always making commits into a branch. By default, this is the main branch.

From the main branch, you can create a new branch using the git switch -c command.

> git switch -c branch1
Switched to a new branch 'branch1'

Think of your repository like a tree. The trunk of the tree is the main branch, and you've just created the first branch on that tree called branch1.

Many Git commands operate on the current branch, also called HEAD. As you make new commits, you'll add them to branch1 instead of main.

Let's create a new file and commit it to branch1.

> echo 1234 > file.txt
> git add file.txt
> git commit -m "Creating my first commit on branch1"

Let's compare the histories of main and branch1 using the git log command.

> git log main
commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84 (main)
Author: Alon Farchy <some@email.com>
Date:   Tue Jul 16 15:34:39 2024 -0700

    Initial commit of my Unity project

> git log branch1
commit 736c35ada5a09ef54737f12ded8bb83d92cdc9d3 (HEAD -> branch1)
Author: Alon Farchy <some@email.com>
Date:   Sun Jul 21 19:24:54 2024 -0700

    Creating my first commit on branch1

commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84 (main)
Author: Alon Farchy <some@email.com>
Date:   Tue Jul 16 15:34:39 2024 -0700

    Initial commit of my Unity project

You can see that the history of branch1 also contains the history of main, but the main branch hasn't been changed.

We can always go back to the main branch and make a commit there.

> git switch main
Switched to branch 'main'

> echo 4567 > file.txt
> git add file.txt
> git commit -m "Added file.txt to main"

Now let's look at the history of each branch

> git log main
commit 855678981c8179c05baaf17c29090726976f6860 (HEAD -> main)
Author: Alon Farchy <some@email.com>
Date:   Sun Jul 21 19:29:17 2024 -0700

    Added file.txt to main

commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84
Author: Alon Farchy <some@email.com>
Date:   Tue Jul 16 15:34:39 2024 -0700

    Initial commit of my Unity project

> git log branch1
commit 736c35ada5a09ef54737f12ded8bb83d92cdc9d3 (branch1)
Author: Alon Farchy <some@email.com>
Date:   Sun Jul 21 19:24:54 2024 -0700

    Creating my first commit on branch1

commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84
Author: Alon Farchy <some@email.com>
Date:   Tue Jul 16 15:34:39 2024 -0700

    Initial commit of my Unity project

These branches have now diverged, which means that each branch has at least one commit that the other does not.

Merging Branches

To bring these branches back together, we can merge them with the git merge command. This will take the commits in a specified branch and try to combine them with the commits in the current branch.

Let's try merging branch1 into main.

> git switch main
Switched to branch 'main'.

> git merge branch1
Auto-merging file.txt
CONFLICT (add/add): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.

Uh oh. If you've been following these examples, you'll notice that we added file.txt in both branches and gave them different contents. Git doesn't know what you want to do, so it sounds the alarm by calling a merge conflict.

Merge Conflicts

Merge conflicts happen when Git can't automatically reconcile the differences between two commits. This usually occurs when the same line in a file has been changed in both branches. In our case, file.txt was modified in both main and branch1, resulting in a conflict.

When a merge conflict occurs, Git leaves both changes in the file, like so:

<<<<<<< HEAD
4567
=======
1234
>>>>>>> branch1

This notation shows the conflicting sections. Remember that HEAD refers to our current place in history, which is the main branch.

The content between <<<<<<< HEAD and ======= is from the main branch.
The content between ======= and >>>>>>> branch1 is from branch1.

To resolve the conflict, you need to edit the file to contain the correct final content. You might decide to keep one change over the other, or merge the two changes together.

Once you're done merging the file, use git add to stage it for the merge commit. When all files are staged, we can use git merge --continue to complete the merge.

> git add file.txt
> git merge --continue

Asset Conflicts and Merging

Merging your code and text files is straightforward, but what about assets? Two people on your team might edit the same image files, audio files, Unity scenes, prefabs, or many other files in your project. This can cause a big problem because these assets are not easy to merge. In the worst case, one teammate will have to redo their work.

Let's address this problem with two strategies:

How to avoid asset conflicts.
How to use Unity's YAML merge tool to merge scenes and prefabs.

Before you go further, make sure your Unity project is set to Visible Meta Files and Force Text (Project Settings > Editor). This makes scenes and prefabs readable in Git diffs and greatly improves merge success.

How to Avoid Asset Conflicts

If there's no conflict, there's nothing to merge. Problem solved! But how can you actually avoid conflicts?

Let's take an example scenario. One developer is adjusting the jump parameters of a character by editing fields on the components attached to the character. Another developer is updating the colors and fonts of the main menu. If the UI and the character are both in the same scene, then there will be a conflict on the scene asset.

Break up your Scenes

We can avoid this conflict if the character and the main menu were each separate prefabs. Each developer could update the prefab instead of updating the scene.

Taking this strategy to its logical conclusion, you can avoid many asset conflicts by moving every GameObject in the scene into its own prefab.

Hint: Sometimes you'll accidentally edit a prefab in the scene. Oops! Fortunately, Unity has a solution for this. Find the Overrides dropdown on the root GameObject of your prefab. Not only can you see which fields have been edited, but you can also apply those edits to the prefab. Nifty!

Sometimes, you'll end up with a very large prefab. For example, maybe the whole UI for the game is in one big prefab. Now you might get asset conflicts on this large prefab.

We can fix this with the same strategy: break up the large prefab into smaller prefabs. It's up to you to balance the complexity of more prefabs and the risk of asset conflicts.

If done correctly, the only time the scene or large prefab needs to be edited is:

To add or remove a prefab, or
To drag a reference from one prefab into the component property of another prefab.

It's possible to avoid the first case by instantiating all of your prefabs at runtime. You will have to decide for yourself if this tradeoff is worth the effort.

But how do we deal with the second case: references across prefabs?

Avoiding Asset References: Dependency Injection and Service Locator

In any beginner's guide to Unity, you learn how to create public properties on your components which appear as editable fields in the editor. If these properties are a component type or GameObject type, then you can drag other GameObjects from the scene into these fields and Unity will inject them into your component. Magic.

While convenient, these references can cause frustrating asset conflicts in two ways. First, they simply create more reasons for you to edit your assets. Second, if these references are between separate prefabs, then you end up having to edit the scene to set these references. This reduces the benefits of breaking the scene up into prefabs.

This problem isn't just an asset problem. It's actually a well known problem in software architecture: how do you get separate parts of your code to access each other? Martin Fowler, a well known software engineer, wrote a great article on this topic. Cutting to the chase, you have two options:

Dependency Injection: The entity instantiating your component hands you the references you need.
Service Locator: You look up the references you need in a well known table (the service locator).

When you drag objects into fields in the scene, Unity is effectively performing dependency injection for you by 'injecting' references to your component at runtime. Unfortunately, this forces you to edit the scene, which creates merge conflicts.

Instead, you can use a dependency injection library or a service locator library help you solve this problem. At Virtual Maker, we use a custom service locator library, but here are some open source options you can choose from.

VContainer: A dependency injection library that is "light and fast".
Extenject: A dependency injection library forked from Zenject with lots of features.

How to use Unity's YAML merge tool to merge scenes and prefabs.

Ok, so you broke up your scene into prefabs, but now two developers have added new prefabs to the scene. What do you do?

Meet your new best friend: UnityYAMLMerge. This is a "mergetool" which will attempt to automatically merge scenes and prefabs. In simple cases, like two developers adding or removing different prefabs to the scene, it can resolve the conflict correctly by adding or removing the correct prefabs.

Unfortunately, this is not a get out of jail free card. You might still hit unresolvable conflicts, like two developers changing the same transform's position. In this case, you'll have to manually merge the files.

Unity stores its scenes, prefabs, and many other asset files in a YAML text format. For simple conflicts like a transform position change, you can edit the YAML files directly to merge the changes.

It's also possible for UnityYAMLMerge to do the wrong thing in complicated situations. Suppose one developer unpacks a prefab in the scene, and another developer overrides a value in the same prefab. UnityYAMLMerge will end up keeping both versions of the prefab in the scene.

Git Clients: UI for Git!

While the command line is a powerful tool for working with Git, many developers prefer to use Git clients for their graphical interfaces and additional features. Git clients can make managing repositories more intuitive, especially for those who are new to version control or prefer a visual approach.

Important: Even if you use one of these Git clients, it is important to install the Git command line tools. Not only are these tools useful in a pinch, but they are required for Unity to install git dependency packages!

Below are some of the most popular Git clients available:

GitHub Desktop

GitHub Desktop is a free, open-source Git client developed by GitHub. It is designed to simplify the Git workflow, making it accessible for both beginners and experienced developers.

SourceTree

SourceTree is a free Git client developed by Atlassian. It supports both Git and Mercurial repositories and offers a rich set of features for managing your version control workflows.

GitKraken

GitKraken is a cross-platform Git client known for its elegant interface and robust features. It is designed to streamline Git workflows and improve productivity.

Tower

Tower is a powerful Git client available for macOS and Windows. It offers a comprehensive set of features designed for professional developers and teams.

Fork

Fork is a fast and friendly Git client for macOS and Windows. It focuses on providing a simple yet powerful interface for managing Git repositories.

Git on the Web: GitHub for Unity Developers

So now we know how to use Git for version control. Now we'll learn how to backup your project and start collaborating with a team.

GitHub is a web-based platform that hosts Git repositories. It provides tools for collaborative development, code review, and project management. By pushing your local Git repository to GitHub, you can collaborate with others, track issues, and more.

We use GitHub here as an example, but there are also other hosts you could explore like GitLab and BitBucket.

Pushing your Unity Project to GitHub

To push your local repository to GitHub, follow these steps:

Create a free account on GitHub.
Create a new repository on GitHub.

Set these options:

No template
Choose yourself as the owner and give your repo a name.
Choose Private unless you want your project to be available to anyone on the internet.
Leave Add a README file unchecked, since we'll be pushing our own content.
Don't add a .gitignore, since you already have one.
Leave License as None if you chose Private, or choose an appropriate license.
Click Create repository.

Push your changes using these commands, replacing {org} and {repo}:

> git remote add origin https://github.com/{org}/{repo}.git
> git push -u origin main

Congratulations, your project is now backed up to GitHub! You can test this by "cloning" your repository to another device or folder using the git clone command:

> git clone https://github.com/{org}/{repo}.git

Each time you make a commit, you can git push your branch to GitHub and then git pull those changes from GitHub to one of your other clones.

# Machine 1
> git push

# Machine 2
> git pull

Working with a Team: GitHub Organizations

A GitHub organization is a shared account for collaborative projects. It allows teams to manage permissions, streamline access, and consolidate billing. Key features include:

Team Management: Group members into teams with different access levels.
Repository Permissions: Control who can push, review, and administer repositories.
Project Management: Use tools like GitHub Projects for task tracking and progress management.

As of May 2026, creating an organization on GitHub is free with limited features.

To create an organization, click your profile picture > Your organizations > New organization.

Once you've created an organization, you can either create a new repo or transfer an existing repo to the organization in the Settings page for that repo.

Creating Your First Pull Request

When working on a team, it's often important for team members to review each other's changes before merging them into the main branch or release branches. In Git nomenclature, this review process is called a "pull request" because you're making a request to your team to pull your changes into another branch.

There are several critical advantages to using pull requests:

Team members can catch each other's mistakes.
Team members can suggest alternative ways to fix a bug or implement a feature.
Automation can run with each pull request to build the Unity project for playtesting or perform other checks.
By their nature, pull requests create a clear history of changes going into the main branch, allowing individual bug fixes or features to be reverted if necessary.

Creating a new branch for your pull request

Let's start simple by making a trivial pull request. First, we need to make a new branch to do our feature development.

# Go to the main branch and get the latest changes.
> git switch main
> git pull

# Create a new branch off main
> git switch -c dev/test-feature

This command creates a new branch from main called dev/test-feature. The dev/ part is a naming convention we like to use to separate developer branches from the main branch.

As a test, let's add a new text file to your repository and make a new commit:

> git add path/to/my_file.txt
> git commit -m "Adding my_file"

Finally, push this branch and all of its commits to GitHub:

> git push -u origin dev/test-feature

After the first time you push a branch, you can just use the shorthand git push.

Creating a new pull request

Now let's go to GitHub and create a pull request:

Go to your repo: https://github.com/{org}/{repo}
Click Pull requests
Click New pull request
Set the base to main and compare to dev/test-feature.
Add a title and description
Click Create pull request

This will take you to your pull request page.

Review the pull request

From the pull request page, there are many options. Most importantly, your team can click the Files changed tab to start reviewing the pull request.

Once you start a review, you can add comments to individual files. Important: your team won't see your comments until you finish your review.

Once you're done making comments, click the Review dropdown and finish your review.

Update your Pull Request

At any point during the review process, you can create a new commit, and use git push to update your branch on GitHub. The pull request will be automatically updated with your changes.

Complete the pull request

Once you've answered all your team's comments and are ready to complete your pull requests, navigate back to the Conversation tab and locate the Merge pull request button. If you click the dropdown, you'll see some options:

Create a merge commit
Squash and merge
Rebase and merge

Creating a merge commit is the most straightforward option. It creates a new merge commit in your target branch (main) that combines your branch and the target branch together. All of the commits you made will appear in the main branch history.

Squash and merge is another popular option, where all your commits are "squashed" into one commit which is added to the main branch. This keeps the main history "clean" by not including all the little commits you made while developing your bug or feature, but in exchange you lose those details in your Git history.

Don't use Rebase and merge unless you really know what you're doing.

Summary of the Pull Request flow

In a team that embraces pull requests, each member uses the following workflow:

Create a new branch off main in which to do feature or bug work.
Commit often to this branch and push those changes to back them up.
When ready, create a pull request back to the main branch.
The team reviews the pull request. Automation also runs to build the project or run tests.
Commit and push additional changes as needed.
When all review comments are resolved, and all automation passes, complete the pull request.

Sharing Code and Assets Between Projects: Submodules vs Unity Packages

Once you've gotten the hang of storing your Unity projects in Git repositories, you may run into a situation where you have the same code and assets in multiple projects. You might then find yourself making changes in one project, and then having to repeat those changes in the second project. And the third project.

So, you may be thinking -- is there a good way to share assets between repositories?

Here be Dragons!

Beware! Sharing assets between repos comes at a considerable cost:

The project organization becomes more complicated, which makes it harder for your team to understand.
Making changes to the shared assets becomes more difficult because multiple projects depend on them.
The Git history is now split between the main repository and the shared assets. It becomes an extra chore to keep them in sync.

To avoid these issues, some teams opt to use a monorepo, which is a big repository with multiple projects. To give you an extreme example, Microsoft opted to host all of Windows in a single repository. This required making changes to Git to cope with the millions of files.

Ok, you've been warned. If you're still convinced your projects will benefit from sharing assets between repos, then you have two main options:

Git Submodules

Git submodules are the Git-based solution to the sharing problem. A submodule is just a pointer from one repository to a commit in another repository. So, all you have to do is create a separate repository for your shared assets, then add a submodule to each of your projects. Sounds simple right?

Unfortunately, it's not so simple in practice. Developers on the project need to be aware that submodules exist and to keep their local repo updated with the latest submodules. This makes the learning curve for Git steeper for new developers.

When should you use Submodules? If the code or assets you're trying to share are in Unity, we recommend creating a Unity Package (see below) and using the Unity Package Manager (UPM) to pull it into different projects. Package dependencies are more automatic and can be properly versioned.

But if your shared assets are outside of Unity, then use submodules.

How to add a submodule to your repo

First, create a new repo with your shared assets. We'll pull this repo into your main project repo as a submodule.

Navigate to the directory where you want to add your submodule and use the git submodule add command.

> cd main_repo/path/to/somewhere
> git submodule add https://github.com/{org}/{submodule_repo}

> git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   ../.gitmodules
        new file:   {submodule_repo}

You'll notice git added or modified the .gitmodules file. You'll also notice your repo appears like a "new file". It's a bit misleading - Git is actually just telling you that the submodule is staged to be committed.

Commit these changes:

> git commit -m "Add submodule"

Now you need to know how to work with the submodule. If you cd into the submodule folder and start using git commands like git log, it will look just like you cloned this repository in a normal way. You can switch branches here, make changes, commit, push, etc.

However, any time you make changes, the parent repository will detect those changes. For example, if I add an untracked file to the submodule:

> git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)
        modified:   {submodule_repo} (untracked content)

It doesn't tell me which files have changed, just that there are changes. If I go back to the submodule and commit this file, then I get a different kind of message:

> git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   {submodule_repo} (new commits)

Now Git recognizes that the submodule has a new commit, but we haven't updated the pointer in the main repo to point to that new commit. We need to make another commit in the project repo to update that pointer.

git add {submodule_repo}
git commit -m "Update Submodule"

Great - now the main repo and the submodule are in sync! But how do we push this update to our team? This is where things get tricky.

By default, git push will only push the current repo to its remote origin, but it will not push the submodule. You need to remember to do git push in the submodule directory too.

To review this change with your team, you need to create two pull requests - one in the submodule repo, and another in your main repo. If you need to make more changes in the submodule, you need to go through the whole process again:

Make a commit in the submodule
git push that commit.
Make a commit in your main repo
git push that commit.

Once you're finished with your changes and you complete your two pull requests, it's time for your team to pull your changes. First, they check out and pull the branch where you added the submodule.

> git switch main
> git pull

If they go looking for your newly added submodule, what they'll notice is that the submodule directory is empty. To tell Git to recognize new submodules, use the git submodule init command.

git submodule init

Now Git recognizes the submodule exists, but it hasn't checked out any files. Each time you update the submodule with new commits, your team needs to run:

git submodule update

Read the Git Submodule documentation for additional commands.

Unity Packages

If the code or assets you want to share are in Unity, we highly recommend using Unity Packages over submodules. While they are a bit of work to set up, they are easier to version and will automatically keep your team in sync.

For reference, Unity has some good documentation for custom packages. In this example, we'll create an "embedded" package, and then move it to a separate repository to be shared.

To create an embedded package, create a folder inside the Packages folder called com.{org}.{package-name}. Then, add this package.json file to it:

{
    "displayName": "Package Name",
    "description": "This package does XYZ",
    "name": "com.{org}.{package-name}",
    "unity": "2020.3",
    "version": "1.0.0",
    "category": "utilities"
}

Now, we can hop over to Unity and start adding assets to our package. Your package should appear as a folder in the Project window under the Packages section.

If you want to add code to your package, then you'll also need to create an assembly definition file: Assets > Create > Assembly Definition. This ensures your package code is compiled separately from the main project. Learn more about Assembly Definition and packages.

Once you're happy with your package, you can move it to its own repository, so it can be shared with other projects. Create a new repository and move the whole package into it.

If you want your package to be open source, you can use OpenUPM to distribute your package with the Unity open source community. Learn how to distribute your package with OpenUPM.

If you want to keep your package private, then you can use a Git reference to pull it into your Unity projects.
Open the Package Manager and go to + > Add package from git URL....

Copy and paste the URL to your package's Git repository, and add .git on the end:

https://github.com/{org}/{repo}.git

If all goes well, you'll see your package in the Project window as before. Check which changes Unity made with git status:

git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   Packages/manifest.json
        modified:   Packages/packages-lock.json

Unity stores the list of packages you use in Packages/manifest.json. Here, you'll find all of the built-in Unity packages and your newly added package. You can also see the same list of packages in the Package Manager window in Unity.

Also pay attention to the Packages/packages-lock.json file. This is where Unity stores the specific version of each package that your project uses. By tracking this file in Git, you can ensure your whole team is using the same version of every package and its dependencies.

Since you added your package from a Git URL, the packages-lock.json file will store the latest commit ID that Unity found when you added the package.

"com.virtualmaker.servicelocator": {
    "version": "https://github.com/virtual-maker-net/com.virtualmaker.sharedcode.git",
    "depth": 0,
    "source": "git",
    "dependencies": {},
    "hash": "ba0619eac92235362b45e791b70ac2637ce73900"
  },

The "hash" field is the commit ID. You can edit the packages-lock.json file directly to update the commit ID, but it's usually better practice to specify the commit ID in the manifest.json file. For example:

"com.{org}.{package-name}": "https://github.com/{org}/{repo}.git#0fde24173316721063c9b46ec35fa8cf261e6531"

A better way is to use git tags to version your package and pass in the specific tag name.

First, create and push a tag in your package's repo:

> git tag 1.2.0
> git push --tags

Then, use it in manifest.json:

"com.{org}.{package-name}": "https://github.com/{org}/{repo}.git#1.2.0"

Git on a Team: Branching Strategies for Unity

The way we've discussed branching so far is:

Create dev/ branches for features and bug fixes.
Create pull requests from dev/ branches to the main branch.

During development, this is usually an excellent strategy because it is simple to follow and keeps things organized. Before releasing your game, we recommend using this strategy exclusively.

You may be tempted to create branches for separate teams to work in. Avoid it if you can. Each team will be working on and testing a different version of the product, doubling your QA efforts. Merging those team branches also becomes a big chore and often results in regressions. You can end up with developers whose entire job is to merge branches together.

You may be also tempted to create a new branch for a demo. Resist the temptation -- your demo branch will quickly drift from your main branch, and it will become impossible to merge back together. If you absolutely must create a demo branch, be prepared to throw away all work targeting that branch.

Release Tags

At some point, you'll be ready to release your game. Congratulations!

As soon as you release, there become two versions of your game:

The released version of your game
The development version of your game, where you're making bug fixes and feature updates.

You will want to keep track of the released version of your game for multiple reasons:

You may want to debug an issue found only in the release version of your game.
You may need to compare the release and development versions to diagnose regressions.
In rare cases, you'll need to apply an immediate hotfix to your game. The issue is so critical that you won't be able to wait for the development version to stabilize for release.

Our strategy at Virtual Maker is to follow trunk-based development. Essentially, always keep your developers creating pull requests to the same branch (main).

Each time you make a release, create a new version tag. This tag largely exists as a reference by your team. Developers can use the version tag to test bug reports and compare changes with the main branch. The ONLY time you should make a new branch from a release tag is for an emergency hotfix.

Automated Unity Builds and CI/CD with GitHub Actions

One of the best things about GitHub is the robust CI/CD infrastructure called GitHub Actions. Using actions, you can automatically:

Build your Unity project for multiple platforms.
Run unit tests
Perform asset validation
Perform style checking
Deploy your game to one ore more app stores.

Better yet, you can configure your actions to run on each pull request, forcing developers to fix issues before they even make it into the main build.

Unfortunately, setting up GitHub actions for Unity is complicated, to say the least. You need to deal with installing Unity, activating a Unity license, adding build extensions to the Unity editor, and more. Build Unity also takes a lot of compute time. Not only does that cost you money, but it makes your team's pull requests drag on as developers wait for their changes to build.

But hope is not lost! Here at Virtual Maker, we've developed a solution...

Buildalon: The one-stop solution for Unity automation.

Learn more about Unity automation at our website at buildalon.com.

More by Virtual Maker

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

Git and Unity: A Comprehensive Guide to Version Control for Game Devs

Quick Summary

Prerequisites

Table of Contents

Why You Need Version Control for Unity

Timmy the Clever Game Developer

Timmy Discovers Source Control

What is Git?

Basic Concepts

How to Initialize a Git Repository for Your Unity Project

What is a .gitignore?

Using Git LFS with Unity To Track Large Assets

Tracking specific files with LFS

Pattern matching files with LFS

Making your First Commit

Useful Git Commands for Unity Developers

Commit Early, Commit Often

Help, I made a boo boo!

Branching and Merging

Merging Branches

Merge Conflicts

Asset Conflicts and Merging

How to Avoid Asset Conflicts

Break up your Scenes

Avoiding Asset References: Dependency Injection and Service Locator

How to use Unity's YAML merge tool to merge scenes and prefabs.

Git Clients: UI for Git!

GitHub Desktop

SourceTree

GitKraken

Tower

Fork

Git on the Web: GitHub for Unity Developers

Pushing your Unity Project to GitHub

Working with a Team: GitHub Organizations

Creating Your First Pull Request

Creating a new branch for your pull request

Creating a new pull request

Review the pull request

Update your Pull Request

Complete the pull request

Summary of the Pull Request flow

Sharing Code and Assets Between Projects: Submodules vs Unity Packages

Here be Dragons!

Git Submodules

How to add a submodule to your repo

Unity Packages

Git on a Team: Branching Strategies for Unity

Release Tags

Automated Unity Builds and CI/CD with GitHub Actions

Buildalon: The one-stop solution for Unity automation.

More by Virtual Maker

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