CI/CD Unity Projects using GitHub Actions
Objective:
Build a “smoking hot” CI/CD process to build, test and automatically deploy Unity projects.
The back story:
I’m a long time veteran of web development with over 20 years in media publishing, development and solutions architecture. There’s a pretty deep culture in software development for Continuous Integration and Continuous Deployment (CI/CD) pipelines. Don’t be fooled, the real reason for such things is that programmers are lazy (as they should be) and don’t like to repeat mundane tasks — sure, there’s the real benefits such as productivity gains, test coverage and quick release cycles. We all know the real reason. 😉
I’m new to Unity Development and digging into serious C# software engineering in a pivot to my professional career. I wanted to see if there were any CI/CD pipelines for Unity as there are for Web and other software development…surely there had to be? A quick search on “unity3d ci github actions” pointed me in the direction of Game.ci. This is my journey to automate the deployment of my Space Shooter Pro game so folks can play the web version, since downloading executables from strangers is super sus! (don’t do it…ever)
Get up to speed (if needed):
If you don’t know what CI/CD is or what GitHub actions are or how to use them, here are a few resources that I’ve used in the past and what I used as part of this write-up:
- GitHub Actions Docs (read the docs!)
- GitHub Setup a workflow
- Game.ci Docs (read the docs!)
- Dave Farley’s Continuous Delivery YouTube Channel
Step 1 Activation:
In order to build your Unity projects you’re going to need to be able to validate that you have the ability to do so with Unity. The following is pretty much direct copy and paste (aka plagiarism) from Game.ci’s Activation documentation. I’m only running through the process for a personal license workflow since I don’t have the needs (yet) for a professional license.
In your GitHub (GH) repo make a file called.github/workflows/activation.yml (you can call it whatever you want, but activation is describing what we’re trying to do)
with the following markup:
name: Acquire activation file
on:
workflow_dispatch: {}
jobs:
activation:
name: Request manual activation file 🔑
runs-on: ubuntu-latest
steps:
# Request manual activation file
- name: Request manual activation file
id: getManualLicenseFile
uses: game-ci/unity-request-activation-file@v2
# Upload artifact (Unity_v20XX.X.XXXX.alf)
- name: Expose as artifact
uses: actions/upload-artifact@v2
with:
name: ${{ steps.getManualLicenseFile.outputs.filePath }}
path: ${{ steps.getManualLicenseFile.outputs.filePath }}Commit this and push up to GH.
- We’re going to manually run this workflow.
- Download the artifact that gets generated by the above workflow
- Visit license.unity3d.com and upload the
Unity_v20xx.x.xxx.alf - You should now have a license file (Unity_v20xx.x.ulf). It’s ok if the numbers don’t match your Unity version. KEEP THIS FILE SECRET!
- We need to add this to your GH Secrets: Open
GitHub > <your repo> > settings > Secrets - Create the following secrets:
*UNITY_LICENSE— (copy the contents of the.ulffile)
There are additional steps noted in the Game.ci documentation that you should absolutely implement if you’re needing to use a professional license, for example, freeing up the license allocation after it’s used — but this is out of scope for my needs. If it ever becomes in scope, then I’ll for sure update this write up.
Step 2 Test runner:
Tests are important. Tests can be hard. Currently tests are out of scope for this walkthrough but I’ll likely write about it in the future as I get into writing up actual Unity Development. I’m going to just show how to set up the test runner should your project have tests to actually run.
You’re going to make a new file: .github/workflows/template.yml with the below markup. I’m not going to go into the details of the contents, Game.ci has an extremely well documented explanation of what each section does.
Add and commit this to your GH repo and after a few minutes you should see the action has ran successfully as long as you didn’t miss a step above. If you see any failures, make sure you followed the steps to add the secret — and spelled things right…or maybe I didn’t spell things right 🙄 Also, spaces matter with .yml so make sure the format from the gist above was properly indented when you pasted into your editor. I had a spacing issue when I lifted the template code from off of game.ci
Step 3 Building:
For this write up I’m going to show the building process for generating the WebGL version of my project. You’ll likely want to setup builds for the targeted platforms your project will release for. Since I’m trying to make a GH page where folks can play my game on the web and not expose themselves to evil crackers. Be sure to read the extensive Game.ci documentation on the build process
For my build process I’m keeping the dependency of the test runner being successfully completed so I don’t build something that’s failed testing. Your workflow maybe different and if so then delete the test runner job and the dependency. Your build workflow may also require that this build step be something outside of the general on: push — for example, you may want it to only be on merge into your main branch or which ever branch you use to manage releases on. For me, having things on: push works.
Step 4 Deployment:
I want folks to be able to play my game without the risk of downloading some stranger’s executable file. Unity’s awesome WebGL build support in concert with GH pages is how I’m going to go about it.
Your final workflow action should look something like this now:
And sadness…
This one took a little sleuthing but found a setting in the player settings for that allows for decompression fallback: Edit > Project Settings > Player > WebGL > Decompression Fallback Check the checkbox and push the change to GH.
And finally success!
The next time we visit our pages page we get what we were expecting! It’s not much right now as of this write up since it’s basically an out of the box Unity project at this point but over the coming days a playable game will emerge!
Coming up in my next post:
I’ll be chronicling my process as I finish my Unity 2D Space Shooter Pro project as I dip my feet into my game dev journey. I hope you follow along, I might save you a few minutes scratching your head.
