Unity CI/CD Demystified: Part 1: One-Time Setup

Published on

Last Updated on

Estimated Reading Time: 3 min

unity tutorial devops

Adding CI/CD to Unity projects is a game-changer, even if you're not a CI/CD enthusiast.

In this series, I'll guide you through setting up a robust CI/CD pipeline for Unity projects using GitHub Actions and GameCI.

Part 1 of this series covers the essential one-time setup for a successful CI/CD pipeline.

Note: These setup steps can be skipped if you've already performed them for a previous project.

Acquire an Activation File for GitHub Runners

Note: The activation file uses machine identifiers, so we need to generate a license for GitHub runners.

  1. Create a file named .github/workflows/activation.yml and add the following workflow definition:
name: Acquire activation file  
on:  
  workflow_dispatch: {}  
jobs:  
  activation:  
    name: Request manual activation file 🔑  
    runs-on: ubuntu-latest  
    steps:  
      # Request manual activation file  
      - name: Unity - Request Activation File  
        id: getManualLicenseFile  
        uses: game-ci/unity-request-activation-file@v2.0.0  
      # Upload artifact (Unity_v20XX.X.XXXX.alf)  
      - name: Expose as artifact  
        uses: actions/upload-artifact@v3
        with:  
          name: ${{ steps.getManualLicenseFile.outputs.filePath }}  
          path: ${{ steps.getManualLicenseFile.outputs.filePath }}

In this workflow, we use GameCI to request the activation file and upload it as an artifact. The workflow_dispatch event enables manual triggering of this workflow.

  1. Manually run the above workflow
    Run workflow manually

  2. Download the manual activation file that appears as an artifact and extract the .alf file from the zip
    Download Artifact

  3. Visit license.unity3d.com and upload the alf file.
    Upload Alf file.png

Note: If you don't see the option for activating a "Unity Personal license", follow the steps at Workaround for Unity Personal License Manual Activation Not Supported.

  1. Download the ulf file. The numbers don't have to match the Unity version exactly.

Install Ruby

  • Install Ruby from here
  • Verify the installation by running ruby -v.
  • Install Bundler by running gem install bundler

Setup Codesigning with GitHub Actions

  • Create a private GitHub repository to store the certificates and code-signing identities we generate.
  • In the private repository, navigate to Settings -> Deploy Keys -> Add Deploy Key
    Add a new deploy key
  • Generate an SSH key. We can use 1Password or use the ssh-keygen utility.
  • Paste the public key (starting with ssh) into the "Key" field.
  • Select Allow write access to enable pushing certificates to the repository.
    Add key

Generate a GitHub Personal Access Token

We need a Personal Access Token to enable our GitHub Actions to access the private GitHub repository where we'll store our certificates.

  • Go to Settings -> Developer Settings -> Personal Access Tokens -> Tokens (classic).
  • Click Generate Token.

Generate Personal Access Token

  • Give the token all repo permissions.

Token Scopes

Setting up Secrets for GitHub Actions

On GitHub, navigate to Settings -> Secrets and Variables -> Actions.

Adding secrets

Create the following secrets

  • UNITY_EMAIL: Your Unity login email address.
  • UNITY_LICENSE: The contents of the .ulf file.
  • UNITY_PASSWORD: Your Unity login password.
  • GH_PAT: The Personal Access Token we generated. Make sure that there is an empty newline at the end.
  • MATCH_PASSWORD: This is an additional layer of security required for encrypting/decrypting certificates.
  • MATCH_REPOSITORY: The name of the private GitHub repository that will store our certificates in the format organization/repository.
  • MATCH_DEPLOY_KEY: This is the private part of the SSH key we created in the private repository to store our certificates.

I recommend adding these secrets at the organisation level so that we can reuse them across multiple projects. We can then selectively grant access to each secret for specific repositories.

Conclusion

This one-time setup paves the way for a streamlined Unity CI/CD pipeline. Stay tuned for the next steps in our journey. Happy coding!!

References