Activation

All actions use a Unity installation, which needs to be activated.

Unity differentiates their methods between personal and professional licenses.

Depending on whether you are using a free or paid version of Unity, you will need to follow the steps for either a personal license or a professional license. Alternatively you can provide the url to a License server.

Personal license

Follow these steps if you are using a free version of Unity.

Note: Do NOT follow the steps for the personal license if you have a professional license.

Mental model

1. Request an activation file for usage on GitHub
2. Use that file to acquire a license
3. Set the license as a secret

About the activation file

You may use the Unity - Request Activation File action with the below instructions.

The activation file uses machine identifiers so you cannot perform this step locally.

Let's go!

Acquiring an activation file

Create a file called .github/workflows/activation.yml and add the below workflow definition to it:

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 and push your workflow definition.

Converting into a license

caution

Unity no longer supports manual activation of Personal licenses

When activating your Personal Unity license, you may encounter an issue where only the "Unity Pro or Plus" option is available, preventing the activation of a Personal license. Here is a workaround to resolve this:

1. Visit license.unity3d.com and upload the Unity_v20XX.X.XXXX.alf file.
2. On the "Activate your license" page, if the "Personal" option is not available, right-click on the page and choose "Inspect" to open the browser's developer tools.
3. Find the line of HTML that looks like this: <div class="option option-personal clear" style="display: none;">.
4. Delete display: none; from the style attribute to make the "Personal" option visible.
5. Now you should be able to select the "Personal" option and proceed with the activation.

You can discuss this issue or find additional assistance in the related Discord conversation or GitHub ticket.

For future reference, activating a license from the command line as documented on Unity's Manual Page might be an alternative solution.

Follow these (one-time) steps for simple activation.

1. Manually run the above workflow.
2. Download the manual activation file that now appeared as an artifact and extract the Unity_v20XX.X.XXXX.alf file from the zip.
3. Visit license.unity3d.com and upload the Unity_v20XX.X.XXXX.alf file.
4. You should now receive your license file (Unity_v20XX.x.ulf) as a download. It's ok if the numbers don't match your Unity version exactly.
5. Open Github > <Your repository> > Settings > Secrets.
6. Create the following secrets;
   • UNITY_LICENSE - (Copy the contents of your license file into here)
   • UNITY_EMAIL - (Add the email address that you use to login to Unity)
   • UNITY_PASSWORD - (Add the password that you use to login to Unity)

GameCI does not acquire nor store your Unity email or password. They are required for reactivating the license during build and test steps.

Note: When changing Unity version, you may need to repeat the same process.

Professional license

1. Subscribe to Unity Plus or Unity Pro, and get your Serial Key from the Unity Subscriptions page
2. Open Github > <Your repository> > Settings > Secrets
3. Create the following secrets;
   • UNITY_SERIAL - (Add the serial key from step 1 that looks like XX-XXXX-XXXX-XXXX-XXXX-XXXX)
   • UNITY_EMAIL - (Add the email address that you use to login to Unity)
   • UNITY_PASSWORD - (Add the password that you use to login to Unity)

GameCI does not acquire nor store your Unity email or password. They are required for reactivating the license during build and test steps.

Note: Do NOT follow the steps for the personal license if you have a professional license.

License Server

If you host your own Unity license server you can provide its url using unityLicensingServer. A floating license will be acquired before the build, and returned after.

Example of use:

- uses: game-ci/unity-builder@v3
  with:
    targetPlatform: WebGL
    unityLicensingServer: [url to your license server]

Optional steps

• Verify your license using Activate.
• When using a pro license also use Return License to free up the license allocation after usage.

Note: Test runner and Builder already include these steps.

Next steps

The license can now be used in test and build steps.

You are now ready to start configuring these.