TL;DR: It’s critical to deliver the latest builds of your Unity game to testers and stakeholders. You can automate this process by setting up a Codemagic CI/CD pipeline and either using public Codemagic dashboards to access build artifacts or setting up notifications in Discord with links to builds and release notes.
This post is written by Mina Pêcheux
Let’s see how we can use automation tools to share our game builds with QA testers and stakeholders!
When you start to work on larger projects — and probably within a larger team — you’ll soon discover that in addition to creating assets, developing features, and fixing bugs, you also need all your releases to actually work! This means that you’ll need somebody to test your builds on a regular basis.
This type of role is often called “QA,” which stands for “quality assurance.” QA testers are tasked with trying out the new releases and asserting that a series of tests check out. (It’s a bit like unit testing but involves evaluating more complex situations.) Of course, your stakeholders might also want to have a look at your app’s evolutions regularly to give feedback.
Your app needs to be delivered to both the QA team and the stakeholders on a regular basis. Doing this manually (by sending every build along with its release notes via a Slack channel or similar means) is an option — but not the most convenient one. You need to remember to do this task and dedicate time to it, and it breaks the flow of your work process.
So, how can we create a robust and easy-to-use automated pipeline to send our app’s builds to everyone involved? Simple: We can use a CI/CD platform such as Codemagic.
Learn other reasons why you should use a CI/CD for your Unity projects from this article.
In this article, we are going to:
- Quickly introduce our sample Unity project and set up a simple build workflow on Codemagic
- Discover how we can share our build artifacts (and, optionally, release notes) using Codemagic’s built-in “build dashboards” feature
- Go one step further and learn how to automatically publish the releases on a dedicated Discord channel using a Codemagic CI/CD pipeline!
Note: If you’re already familiar with how to configure a Unity project and the associated Codemagic app for a Windows build, feel free to skip to the second section.
Preparing our Unity project and Codemagic app
For this tutorial, I’m going to be working with a very basic Unity app. It consists of a simple screen with a “Click me!” button to change the background color and a “Quit” button to exit the application. You can find the full sample project on GitLab over here 🚀.
Overall, the setup step is the same as what I’ve discussed in previous Codemagic tutorials, except that this time, I’m going to be building on a Windows Codemagic machine. Windows is the most popular OS for games and gamers, and we are a bit lacking in Codemagic workflow examples with Unity Windows projects, so I’d wager that this is a win-win. :)
In the Build Settings, I’ll select the “Windows” export:
I’ll also add a Windows-dedicated build script to my project (in an Assets/Editor/Build.cs script):
using System.Linq;
using System;
using UnityEditor;
using UnityEngine;
public static class BuildScript
{
[MenuItem("Build/Build Windows")]
public static void BuildWindows()
{
BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions();
buildPlayerOptions.locationPathName = "win/" + Application.productName + ".exe";
buildPlayerOptions.target = BuildTarget.StandaloneWindows;
buildPlayerOptions.options = BuildOptions.None;
buildPlayerOptions.scenes = GetScenes();
Debug.Log("Building Windows");
BuildPipeline.BuildPlayer(buildPlayerOptions);
Debug.Log("Built Windows");
}
private static string[] GetScenes()
{
return (from scene in EditorBuildSettings.scenes where scene.enabled select scene.path).ToArray();
}
}
Now, all that’s left to do is add my codemagic.yaml config file to trigger the right workflow. As shown in one of Codemagic’s sample projects, we should activate the Unity license and build the project at the same time. We’ll then compress the result as a .zip archive:
workflows:
unity-win-workflow:
name: Unity Windows Workflow
instance_type: windows_x2
environment:
groups:
- unity # <-- (Includes UNITY_SERIAL, UNITY_USERNAME, UNITY_PASSWORD)
- discord # <-- (Includes DISCORD_WEBHOOK_URL)
scripts:
- name: Activate license & Build project
script: |
cmd.exe /c "$env:UNITY_HOME\\Unity.exe" -batchmode -quit -logFile -projectPath . -executeMethod BuildScript.BuildWindows -nographics -serial $env:UNITY_SERIAL -username $env:UNITY_USERNAME -password $env:UNITY_PASSWORD
- name: Export Unity
script: |
cd win
7z a -r release.zip ./*
artifacts:
- win/*.zip
publishing:
scripts:
- name: Deactivate license
script: cmd.exe /c "$env:UNITY_HOME\\Unity.exe" -batchmode -quit -returnlicense -nographics
Then, I’ll go to Codemagic, create a new Unity app, and link it to my GitLab repository. Of course, since we’ll want to authenticate to the Unity ID database to build, we’ll need the same Unity-related environment variables as usual: UNITY_SERIAL, UNITY_USERNAME, and UNITY_PASSWORD. Let’s go ahead and add them in the app’s “Environment variables” tab:
This workflow is explained in Codemagic’s documentation, which we’ve been following so far.
At this point, we’ve set up a basic Codemagic workflow to build our Unity project on a Windows instance. If you run an initial build, you’ll see that we get a release.zip artifact that contains our Windows application:
That’s great, but here, we hit the problem we discussed earlier: Actually accessing this artifact to try out the new version of our app requires us to go to Codemagic, navigate to the builds list, and find the right one…
… which is clearly not ideal for our QA team!
So, now that we’ve implemented our base workflow, let’s see how we can share our artifacts more easily with our kind testers. :)
Sharing builds with Codemagic dashboards
If you’re in a Codemagic team, then build dashboards are one interesting tool at your disposal. They allow you to share public links to easily send your build artifacts and release notes, if there are any, to whomever you want.
Dashboards are made for that exact purpose — they provide a way to quickly distribute an updated version of your apps to your QA testers or stakeholders.
To enable build dashboards for your team, go to your Codemagic team’s settings and open the “Build dashboards” section. Here, you’ll see an “Enable” button that you can click:
As soon as you’ve turned the feature on, you’ll get a new link in the same location to create your first build dashboard:
Once you click on it, you’ll be redirected to a list of your builds with two important buttons in the top-right corner: a “Filters” button to choose which builds to show in the dashboard and a “Share dashboard” button to get its public link.
The filters make it easy to cherry-pick the build(s) you want to share; for example, you can choose to only list the builds that succeeded. For my “Codemagic Dev Tester Collab” app, I can change some of the defaults like this:
Once you’ve properly set up your dashboard, click on the “Share dashboard” button to open a small pop-up that contains the public link:
Now, you can simply copy the link and share it with whomever you want so that they can take a look at these builds’ results!
Codemagic’s Discord integration
Another cool thing about Codemagic’s build dashboards is that they give you a quick overview of a selected list of builds. They’re also a good way to share workflow artifacts with a selected few users.
But it still requires the users to leave whatever they were doing and go visit the dashboard. What if you could have the builds come to you instead of going to them? Luckily, this is also possible: Codemagic offers integrations with email and messengers like Slack and Discord.
Here, we’ll be looking at how to get build notifications in Discord. (We’ve already discussed a similar process for Slack in another article.) Nowadays, Discord is one of the most-used discussion apps for everything game related (be it actually playing games or developing games and communities around them). It’s usually the go-to application for open-source and/or community-based game projects. Discord often contains info about the code source in the creators’ private channels, like the last commits or the current branches.
Codemagic offers an easy-to-set-up Discord integration that enables us to directly send the results of our workflow (with info and artifacts) to a Discord channel whenever our pipeline completes!
The idea is to create a webhook in Discord on a specific channel and then post data to it in the Publishing step of our Codemagic workflow. Let’s see how to do that in detail. :)
Setting up the Discord channel
I’m going to assume that you don’t yet have a Discord server or channel to receive the Codemagic notifications. So first, you’ll need to create a new server in Discord:
In the server creation pop-up, you can leave the defaults as they are on the various screens. You just need to pick a specific name for your server at the end (for example, the name of your game, engine, or project):
Then, in this server, create a new channel dedicated to your build notifications:
Make sure that it’s a “Text” channel, and pick a clear name:
Once you’ve finished creating the channel, click the settings icon to edit it:
Navigate to the “Integrations” section and click the “Create Webhook” button:
Finally, give your webhook a name (this will be the name of the bot that “posts” notifications on the channel), and click the button at the bottom to copy the webhook URL:
We’re now ready on the Discord side. It’s time to go back to our Codemagic app and set it up properly to interact with our new Discord webhook!
Configuring our Codemagic app for Discord integration
First of all, let’s go back to our environment variables and add a new variable called DISCORD_WEBHOOK_URL with the URL we just copied from Discord. We’ll put it in a new “discord” env var group (distinct from the “unity” group we had before):
Then, we’ll simply update our codemagic.yaml config file to use the current workflow data to post a new message on our Discord channel once a new build of our Unity project is ready.
Since we’re building on a Windows machine, we’re going to use the Microsoft PowerShell terminal language to parse, reformat, and push the data to the webhook URL (if you’re not familiar with this language, take a look at this great tutorial on how to use a Discord webhook with PowerShell):
workflows:
unity-win-workflow:
...
publishing:
scripts:
- name: Deactivate license
script: cmd.exe /c "$env:UNITY_HOME\\Unity.exe" -batchmode -quit -returnlicense -nographics
- name: Discord notification
script: |
$commit=("$env:CM_COMMIT".substring(0, 7))
$commit_msg=(git log --format=%B -n 1 $env:CM_COMMIT)
$author=(git show -s --format='%ae' $env:CM_COMMIT)
$artifact = (echo $env:CM_ARTIFACT_LINKS | ConvertFrom-Json | Where-Object -FilterScript {$_.name -EQ 'release.zip'})
$artifactlink = $artifact[0].url
[System.Collections.ArrayList]$embedArray = @()
$desc = @"
``$commit`` $commit_msg
**Artifacts:**
$artifactlink
"@
$embedObject = [PSCustomObject]@{
color = '4289797'
title = "**[$env:CM_REPO_SLUG:$env:CM_BRANCH] ($author)**"
description = $desc
}
$embedArray.Add($embedObject)
$payload = [PSCustomObject]@{embeds = $embedArray}
Invoke-RestMethod -Uri $env:DISCORD_WEBHOOK_URL -Method Post -ContentType 'application/json' -Body ($payload | ConvertTo-Json -Depth 4)
Now, if you rerun the workflow, you’ll get a new Discord notification at the end. The message in the channel will contain all the info about the build, including a commit message and a direct link to the artifacts. All that’s left is to easily transfer this data to your testers or stakeholders. ;)
You can set up different workflows in Codemagic that will be triggered by different events and add different integrations to them.
For example, every time you build after merging something to a dev branch of your Unity project, you can use Codemagic to automate sending the message to a Discord channel with your testers. And for builds that are triggered by merging something to the production branch, the release notes and artifacts can be sent to a Slack channel used by your investors or other stakeholders. It’s pretty flexible, and it’s entirely up to you how to set it up.
Conclusion
Today, we saw how we can tune Codemagic workflows to share our builds and make dev-to-tester collaboration seamless. We also learned about Codemagic’s build dashboards and Discord integration. Now, you have several tricks up your sleeve to send your build’s artifacts to your QA team or stakeholders! If you need any help reproducing this tutorial, you can always ask on Codemagic’s Slack.
I hope you enjoyed this tutorial — and of course, don’t hesitate to share your ideas for other Codemagic/DevOps topics you’d like me to make tutorials on! You can find me on Medium and Twitter.
- You can find the sample project for this tutorial along with the
codemagic.yamlfile on GitLab over here 🚀 - Related docs for setting up a Unity app on Codemagic can be found here
- In case you are not a Codemagic user yet, you can sign up here:
Mina Pêcheux is a freelance full-stack web & game developer. She’s also passionate about computer graphics, music, data science, and other topics! She runs her own blog. Alternatively, you can find her on Twitter.
