Skip to main content
Version: v4 (current)

Activation

There are a few methods available, if you're using gitlab-ci, the easiest method in the current documentation is using gitlab-ci.

Known issue with Unity activation on gitlab-ci: empty license file

If you are having troubles with Unity activation with gitlab-ci, there is currently an issue with recent Unity versions preventing us to retrieve a license file with actual content.

For more details see the following issue: get-activation-file succeeding but giving a 0kb file. Unity Version 2021.2.7f1 and the workaround.

Don't hesitate to contribute and implement a fix 💝

Having issues with activation?

Have a look at the troubleshooting / common issues page.

Unity Personal​

a. Using gitlab-ci​

Once you've added all required files to your project (mainly .gitlab-ci.yml), there should be a manual step that can be triggered for activation.

  1. Visit your project's settings > CI/CD > Variables and add UNITY_USERNAME and UNITY_PASSWORD with your credentials. Make sure to use your Unity3d email address for UNITY_USERNAME.
  2. Push your first commit to your project and visit CI/CD Pipelines.
  3. Locate your latest job, there should be a play button, click on it and click get-activation-file
  4. Wait for the job to run and follow instructions in the console
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.

b. Locally​

All you need is docker installed on your machine.

  1. Clone this project

  2. Pull the docker image and run bash inside, passing Unity username and password to env

    hint: you should write this to a shell script and execute the shell script so you don't have your credentials stored in your bash history. Also make sure you use your Unity3d email address for UNITY_USERNAME env var.

    UNITY_VERSION=2022.3.12f1
    IMAGE=unityci/editor # https://hub.docker.com/r/unityci/editor
    IMAGE_VERSION=3 # https://github.com/game-ci/docker/releases
    DOCKER_IMAGE=$IMAGE:$UNITY_VERSION-base-$IMAGE_VERSION

    docker run -it --rm \
    -e "[email protected]" \
    -e "UNITY_PASSWORD=example_password" \
    -e "TEST_PLATFORM=linux" \
    -e "WORKDIR=/root/project" \
    -v "$(pwd):/root/project" \
    $DOCKER_IMAGE \
    bash

    If your password contains a !, you can escape it like this (example_pass!word):

    ...
    -e "UNITY_PASSWORD=example_pass"'!'"word" \
    ...

  3. In Unity docker container's bash, run once like this, it will try to activate

    xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \
    unity-editor \
    -logFile /dev/stdout \
    -batchmode \
    -nographics \
    -username "$UNITY_USERNAME" -password "$UNITY_PASSWORD"

  4. Wait for output that looks like this:

    LICENSE SYSTEM [2017723 8:6:38] Posting <?xml version="1.0" encoding="UTF-8"?><root><SystemInfo><IsoCode>en</IsoCode><UserName>[...]

    If you get the following error:

    Can't activate Unity: No sufficient permissions while processing request HTTP error code 401

    Make sure your credentials are valid. You may try to disable 2FA in your account and try again. Once done, you should enable 2FA again for security reasons. See #11 for more details.

  5. Copy xml content and save as unity3d.alf

  6. Open https://license.unity3d.com/manual and answer questions

  7. Upload unity3d.alf for manual activation

  8. Download Unity_v2018.x.ulf (Unity_v2019.x.ulf for 2019 versions)

  9. Copy the content of Unity_v2018.x.ulf license file to your CI's environment variable UNITY_LICENSE. Note: if you are doing this on Windows, chances are the line endings will be wrong as explained here. Luckily for you, .gitlab-ci.yml of the example project solves this by removing \r character from the ENV variable so you'll be alright .gitlab-ci.yml will then place the UNITY_LICENSE to the right place before running tests or creating the builds.

Unity Plus/Pro​

  1. Clone this project

  2. Pull the docker image and run bash inside, passing Unity username and password to env

    hint: you should write this to a shell script and execute the shell script so you don't have your credentials stored in your bash history. Also make sure you use your Unity3d email address for UNITY_USERNAME env var.

    UNITY_VERSION=2022.3.12f1
    IMAGE=unityci/editor # https://hub.docker.com/r/unityci/editor
    IMAGE_VERSION=3 # https://github.com/game-ci/docker/releases
    DOCKER_IMAGE=$IMAGE:$UNITY_VERSION-base-$IMAGE_VERSION

    docker run -it --rm \
    -e "[email protected]" \
    -e "UNITY_PASSWORD=example_password" \
    -e "UNITY_SERIAL=AN-EXAM-PLE-SERIA-LKEY-1234" \
    -e "TEST_PLATFORM=linux" \
    -e "WORKDIR=/root/project" \
    -v "$(pwd):/root/project" \
    $DOCKER_IMAGE \
    bash

  3. In Unity docker container's bash, run once like this, it will try to activate

    xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \
    unity-editor \
    -logFile /dev/stdout \
    -batchmode \
    -nographics \
    -username "$UNITY_USERNAME" -password "$UNITY_PASSWORD" -serial "$UNITY_SERIAL"

  4. Wait for the command to finish without errors

  5. Obtain the contents of the license file by running cat /root/.local/share/unity3d/Unity/Unity_lic.ulf

  6. Copy the content to your CI's environment variable UNITY_LICENSE. Note: if you are doing this on windows, chances are the line endings will be wrong as explained here. Luckily for you, .gitlab-ci.yml solves this by removing \r character from the env variable so you'll be alright .gitlab-ci.yml will then place the UNITY_LICENSE to the right place before running tests or creating the builds.