Getting our License

Setting up Continuous Integration with GitHub Actions — Part 2

Last time, we looked at What Continuous Integration and Continuous Delivery are, some factors involved with making a choice on tooling for our project, and a brief introduction to GitHub Actions which is the tool chain we decided to utilize. Today we’re going to go over the details for the process of setting up the CI portion of our CI/CD pipeline in GitHub.

Setting up workflows

Yesterday we defined Workflows by stating “Workflows contain Jobs that contain Steps that are the list of actions to be run on virtualized environments to provide us with our functionality.”

1. Create .github folder in root of project (the ‘.’ at the beginning of the folder name is important)
2. Create a folder named workflows in the .github folder (naming here is also important since it is how GitHub will find the folder)
3. Create 2 files in our folder activation.yml and main.yml. These are going to contain our workflows for creating a request for activation of a Unity license and for our main CI/CD workflow.

Files and Folders for Workflow Setup with GitHub Actions

Anatomy of a workflow file

Our workflow file is written in YAML. It is important to note that tabs and spaces are important in YAML and can invalidate the structure if not used correctly. Let’s quickly go over the basic pieces of the structure we will need.

name

This is the name of workflow and will be displayed in the GitHub interface while the workflow is running and we are looking at the progress.

name property

on

The on keyword is where we set up the event triggers that will cause this workflow to run. Commonly we would set the workflow to run on a push or pull request to a specific branch like so

on property

jobs

The jobs keyword signifies the start of a list of jobs each run on their own virtualized copy of their environment and typically run in parallel (unless specified with dependencies). Each job has an identifier (in our case sample-job is the identifier), you can also specify a name (which displays as part of the interface in GitHub just like the workflow name above), and the runs-on identifier, which allows us to specify what platform or image we would like our virtualized environment to be built on. Some options for this are mac-latest, windows-latest, and ubuntu-latest, though that is certainly not an exhaustive list.

jobs property

steps

As part of the job definition, the steps keyword defines the start of where most of the action happens. This is the list of operations performed during the run of the job and contains operations like grabbing the latest version of the code, building it and uploading the results. Each step can, optionally, have a name as in the job and workflow sections. They can also contain an id property for referencing between steps, the uses keyword provides the name of another action file if you are utilizing one of the github provided actions or the action of another repository, which we will do both. Lastly, the with key work begins a list of parameters to be passed into the function specified in the uses section.

steps property

Checkout your repository using Checkout.

One of the most common actions that we will use in our workflows is checking out a copy of our repository on to the virtualized environment so that we can perform operations on it like performing a build.

Checkout Action

Caching

another very common operation, particularly for us because we are making Unity builds, is to cache some files for use across multiple runs of a job. In our case we want to cache the Library folder from Unity since it can be quite large and is commonly the same across runs. This can and will provide a boost in efficiency and a reduction of the run time subsequent job runs take.

Checkout Action with Caching Action

Activation of a personal license for Unity

Unity offers two types of License, Personal and Professional, and the process of requesting a license file for use on the virtual machines we will be using is slightly different for each. I use the free version of Unity and a personal license, so that is the process we will cover in this article. If you would like to learn more about how to do this with a Professional license, please see the excellent documentation on Game.CI’s website. The VM’s that are used to build Unity projects using Game.CI’s GitHub Actions have a version of Unity installed and it requires the license file to operate and all GitHub VM’s emit the same HardwareId, essentially making them the same machine as far as Unity is concerned for licensing.

Let's open up our activate.yml file that we created in our workflows folder and add the following contents.

Activation Workflow

There are a few things to note with this file. First the workflow_displatch setting in the on step allows us to manually trigger the workflow from the GitHub interface. Secondly, we are uploading the files produced by the execution of the game-ci/unity-request-activation-file@v2 action provided by Game.CI as artifacts from the job so that we can access and download them for the next step (which is manual).

Now we check in our changes and push them to the server.

Manually Running our Activation Workflow

Now that we have the activation workflow file up in our GitHub repository, we need to run it manually. This step is only needed once per repository, so we have not set it up to run on every check in.

It should be noted that GitHub only picks up and displays workflows in the Actions tab for files on the default branch (which is Master for me). If you are using a feature/develop/master branching and merging strategy, like I am, you will have to commit the yml file for activation all the way up to master before it will show in the Actions tab. This is not the case on other source control platforms.

Once we have the workflow accessible in the Actions tab, we can select our workflow from the list on the left side of the screen, and then select the Run workflow drop-down on the right side of the screen, select the branch we want to run the action from and click the “Run Workflow” button.

Manually Running a Workflow

Once the workflow finishes running click on the name of the workflow run to access the results.

Resulting Request File

We should have a file named in the format Unity_v20XX.X.XXXX.alf which we will upload on the Unity site to request our license file. Click on the .alf file in the Artifacts section to download it.

The official documentation for this process can be found at https://game.ci/docs/github/activation.

Converting into a license

Now that we have our request file, we can head over to https://license.unity3d.com, click the Browse button and navigate to our .alf file, click upload, and click next.

Manual Activation — Step 1

On the next page select Unity Personal Edition. Then select the option that best fits your situation. For this project I am choosing “I don’t use Unity in a professional capacity.” Then click the Next button.

Manual Activation — Step 2

Click the “Download license file” button on the next page to receive our license file that has a .ulf file extension.

Manual Activation — Step 3

Storing our Unity License File

We don’t want anyone to have access to our Unity license file, so we are going to store it as a Secret in our GitHub repository.

1. Navigate to your Repository on GitHub
2. Select Settings
3. Select Secrets
4. Click the “New Repository Secret” button

GitHub Secrets

Create a secret called UNITY_LICENSE and copy the contents of your license file into it.

Creating a Secret

Now we have our Unity License stored as a GitHub Secret ready to be referenced in our workflow.

Secret Created

Next Time!

We’ve gotten through the Unity License setup and our first workflow! Now that we have our license stored as a Secret we’re ready to start setting up our main workflow! Next time, that’s exactly what we’ll do. If you enjoyed this article, or want to come along with me as I progress on my journey, follow me at gamedevchris.medium.com.