`.
-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.
+1. **Activate locally** with Unity Hub on your machine and **Locate the `.ulf`** (see the
+ OS-specific paths).
+2. **Extract the serial** from the `.ulf` file.
+3. **Store** serial and Unity credentials in GitLab’s CI/CD Variables:
+ - `UNITY_SERIAL` (extracted from `.ulf`)
+ - `UNITY_EMAIL`
+ - `UNITY_PASSWORD`
-You can discuss this issue or find additional assistance in the
-[related Discord conversation](https://discord.com/channels/710946343828455455/1138586951604248666)
-or [GitHub ticket](https://github.com/game-ci/documentation/issues/408).
+### 1. Setting Up Your Unity License
-_For future reference, activating a license from the command line as documented on
-[Unity's Manual Page](https://docs.unity3d.com/Manual/ManagingYourUnityLicense.html) might be an
-alternative solution._
+1. **Install Unity Hub**: Download and install [Unity Hub](https://unity.com/download) on your local
+ machine.
+2. **Log in to Unity Hub**: Use the Unity account linked to your CI setup to log in. Ensure you're
+ using the correct account to activate the intended license.
+3. **Activate Your License**: Manually activate by navigating to:
-:::
+ - `Unity Hub` > `Preferences` > `Licenses` and click the `Add` button
+ - Select **Get a free personal license**.
-### b. Locally
+ :::info Ensure File Creation
-All you need is [docker](https://www.docker.com/) installed on your machine.
+ Even if a license appears in Unity Hub, a `.ulf` file may not have been created. To ensure the
+ file is generated, make sure to click the `Add` button and proceed with the activation steps. Do
+ not skip this step.
-1. Clone [this project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example)
-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.
+4. **Locate the `.ulf` file**: Depending on your operating system, the Unity license file will be
+ located in one of these paths:
- ```bash
- 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 "UNITY_USERNAME=username@example.com" \
- -e "UNITY_PASSWORD=example_password" \
- -e "TEST_PLATFORM=linux" \
- -e "WORKDIR=/root/project" \
- -v "$(pwd):/root/project" \
- $DOCKER_IMAGE \
- bash
- ```
+ - Windows: `C:\ProgramData\Unity\Unity_lic.ulf`
+ - Mac: `/Library/Application Support/Unity/Unity_lic.ulf`
+ - Linux: `~/.local/share/unity3d/Unity/Unity_lic.ulf`
- If your password contains a `!`, you can escape it like this (`example_pass!word`):
+If you have trouble locating the `.ulf` file, follow these steps:
- ```bash
- ...
- -e "UNITY_PASSWORD=example_pass"'!'"word" \
- ...
- ```
+- **Check activation**: Ensure you’ve logged into Unity Hub and completed the step "3. Activate Your
+ License".
+- **Reveal hidden files**: These folders may be hidden by default, so enable the option to view
+ hidden files in your file explorer.
+- **Use any platform**: Licenses are not tied to a specific Unity version or platform. You can
+ activate the license on any operating system, such as Windows, and use it for builds on another
+ platform, like Ubuntu. Simply retrieve the `.ulf` file from the platform most convenient for you.
-3. In Unity docker container's bash, run once like this, it will try to activate
+### 2. Extracting the Serial from a personal license
+
+1. **Extract your Unity serial** from the `.ulf` file:
+
+ This command decodes the internal `DeveloperData` field to reveal the **serial** used for
+ activation (even for Personal).
+
+ On macOS or Linux:
```bash
- xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \
- unity-editor \
- -logFile /dev/stdout \
- -batchmode \
- -nographics \
- -username "$UNITY_USERNAME" -password "$UNITY_PASSWORD"
+ cat Unity_lic.ulf | grep DeveloperData | sed -E 's/.*Value="([^"]+)".*/\1/' | base64 --decode
```
-4. Wait for output that looks like this:
+ On Windows using Powershell:
- ```
- LICENSE SYSTEM [2017723 8:6:38] Posting
en[...]
+ ```powershell
+ Get-Content Unity_lic.ulf | Select-String -Pattern 'DeveloperData' | ForEach-Object { $_ -replace '.*Value="([^"]+)".*', '$1' } | [System.Convert]::FromBase64String($_)
```
- If you get the following error:
+:::info Expected Serial Format
- > Can't activate Unity: No sufficient permissions while processing request HTTP error code 401
+The serial should look like this: `XX-XXXX-XXXX-XXXX-XXXX-XXXX`.
- 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](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/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](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816).
- Luckily for you,
- [`.gitlab-ci.yml`](https://github.com/game-ci/unity3d-ci-example/blob/main/.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`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)
- will then place the `UNITY_LICENSE` to the right place before running tests or creating the
- builds.
+### 3. Storing the Serial in GitLab CI/CD
-## Unity Plus/Pro
+**Add the extracted serial** to your GitLab project’s CI/CD Variables:
-1. Clone [this project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example)
-2. Pull the docker image and run bash inside, passing Unity username and password to env
+- `UNITY_SERIAL`: The serial extracted from the `.ulf` file
+- `UNITY_EMAIL`: The email address associated with your Unity account
+- `UNITY_PASSWORD`: The password for your Unity account
- _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.
+:::info Variables are not set in your pipelines?
- ```bash
- 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 "UNITY_USERNAME=username@example.com" \
- -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
- ```
+Make sure you unchecked the "protected" checkbox for these variables if you want them to be
+available for all branches and merge requests.
-3. In Unity docker container's bash, run once like this, it will try to activate
+:::
- ```bash
- 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"
- ```
+:::caution Security Warning
+
+Keep your extracted serial and credentials secure. Never commit them to version control or share
+them publicly.
+
+:::
+
+You're all set! The pipeline will use these credentials to activate Unity automatically. 🎉
+
+---
+
+## Professional License
+
+If you have **Unity Plus** or **Unity Pro**, you have an **official serial key** from
+[Unity subscriptions](https://id.unity.com/en/subscriptions). For **GitLab**:
+
+1. **Get your serial** (format: `XX-XXXX-XXXX-XXXX-XXXX-XXXX`).
+2. **Go to** _Settings → CI/CD → Variables_ in your GitLab project:
+ - `UNITY_SERIAL`
+ - `UNITY_EMAIL`
+ - `UNITY_PASSWORD`
+
+:::info Using "protected" variables will make them available only to protected branches
+
+Make sure you unchecked the "protected" checkbox for these variables if you want them to be
+available for all branches and merge requests.
+
+:::
+
+:::caution Security Warning
+
+Keep your extracted serial and credentials secure. Never commit them to version control or share
+them publicly.
+
+:::
+
+You're all set! The pipeline will use these credentials to activate Unity automatically. 🎉
+
+---
+
+## License Server
+
+If your organization uses a **floating license server**, you can supply a server URL with the
+environment variable `UNITY_LICENSING_SERVER` in your GitLab variables. The pipeline (via
+`before_script.sh`) automatically tries to **acquire** a floating license at the start of the job
+and **return** it after. For example:
+
+```yaml
+variables:
+ UNITY_LICENSING_SERVER: 'ssl://your-license-server.company.com:443'
+```
+
+:::info Using "protected" variables will make them available only to protected branches
+
+Make sure you unchecked the "protected" checkbox for these variables if you want them to be
+available for all branches and merge requests.
+
+:::
+
+**No need** to set `UNITY_EMAIL`, `UNITY_PASSWORD`, or `UNITY_SERIAL` if you exclusively use the
+license server method.
+
+You're all set! The pipeline will use the server to activate Unity automatically. 🎉
+
+---
+
+## Debugging activation Locally with Docker
+
+To debug or confirm activation locally (instead of pushing every time), you can run:
+
+```bash
+UNITY_VERSION=2022.3.12f1
+IMAGE=unityci/editor
+IMAGE_VERSION=3
+DOCKER_IMAGE="$IMAGE:$UNITY_VERSION-base-$IMAGE_VERSION"
+
+docker run -it --rm \
+ -e "UNITY_EMAIL=username@example.com" \
+ -e "UNITY_PASSWORD=example_password" \
+ -e "UNITY_SERIAL=EXA-MPLE-SERI-ALKE-Y123" \
+ -v "$(pwd):/root/project" \
+ $DOCKER_IMAGE \
+ bash
+
+# Then inside the container, run:
+xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \
+ unity-editor \
+ -logFile /dev/stdout \
+ -batchmode \
+ -nographics \
+ -username "$UNITY_EMAIL" -password "$UNITY_PASSWORD" -serial "$UNITY_SERIAL"
+```
+
+If it finishes without errors, a `.ulf` should be located in
+`/root/.local/share/unity3d/Unity/Unity_lic.ulf`. You can use or reference that file in your GitLab
+environment.
+
+:::caution Security Warning
+
+Executing shell commands directly in your terminal can expose your credentials in your shell
+history. To avoid this, consider writing the commands to a shell script and executing the script
+instead.
+
+:::
+
+## Next Steps
+
+Once your license is activated in GitLab CI, you can:
-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](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/issues/5#note_95831816).
- Luckily for you,
- [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)
- solves this by removing `\r` character from the env variable so you'll be alright_
- [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)
- will then place the `UNITY_LICENSE` to the right place before running tests or creating the
- builds.
+- Run **Unit tests** with the `test` job in your `.gitlab-ci.yml`.
+- Create **Builds** for multiple platforms (Windows, Linux, macOS, Android, iOS, WebGL).
+- Deploy or publish artifacts (e.g. WebGL to GitLab Pages).
+- Explore advanced usage (e.g., coverage reports, caching, license server expansions).
[common-issues]: /docs/troubleshooting/common-issues
diff --git a/docs/05-gitlab/03-example-project.mdx b/docs/05-gitlab/03-example-project.mdx
index 3b7c3db5..b65f1dd0 100644
--- a/docs/05-gitlab/03-example-project.mdx
+++ b/docs/05-gitlab/03-example-project.mdx
@@ -1,5 +1,13 @@
# Example Project
+:::info You can subscribe to `unity3d-gitlab-ci-example` releases
+
+The gitlab project uses tags to easily track what changes and keep stable versions. See
+[example project's release](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/releases) for
+more details.
+
+:::
+
## About
[The `unity3d-gitlab-ci-example` project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/)
diff --git a/docs/05-gitlab/06-deployment/android.mdx b/docs/05-gitlab/06-deployment/android.mdx
index 7c697057..a9e78558 100644
--- a/docs/05-gitlab/06-deployment/android.mdx
+++ b/docs/05-gitlab/06-deployment/android.mdx
@@ -6,8 +6,8 @@ Unity license in your CI's environment variable : `UNITY_LICENSE_CONTENT_ANDROID
required anymore now that images share a base image
[See related change](https://gitlab.com/game-ci/unity3d/merge_requests/63)_
-By default the apk is not signed and the build will use the Unity's default debug key. For _security
-reasons_, **you should not add your keystore to git**.
+By default, the apk is not signed and the build will use the Unity's default debug key. For
+_security reasons_, **you should not add your keystore to git**.
## Encode your keystore
@@ -43,12 +43,12 @@ The bundle version code must be increment for each deployed build.
To simplify the process, the `BUNDLE_VERSION_CODE` env var is used and set as bundle version code.
Currently, for gitlab, `BUNDLE_VERSION_CODE = $CI_PIPELINE_IID`.
-[Documentation](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
-If you use another CI solution, set a CI env var incrementing for each pipeline.
+[Documentation](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) If you use
+another CI solution, set a CI env var incrementing for each pipeline.
-### Fastlane supply (deployement)
+### Fastlane supply (deployment)
-Follow [setup instructions](https://docs.fastlane.tools/actions/supply/) to get a google play
+Follow [setup instructions](https://docs.fastlane.tools/actions/supply/) to get a Google Play
console token, then, add the content to env var `GPC_TOKEN`.
Uncomment the `#deploy-android` job in gitlab-ci.yml and replace `com.youcompany.yourgame` by your
@@ -72,7 +72,7 @@ gem "fastlane"
and then copy the file to the current directory prior to installing the gem. eg
`cp $CI_PROJECT_DIR/Gemfile .`.
-That is the simplest way with command line but you can also make `fastlane/Fastfile` and
+That is the simplest way with command line, but you can also make `fastlane/Fastfile` and
`fastlane/Appfile`, with the following command after building a temporary gradle project (export
gradle project option in Unity build settings):
diff --git a/docs/05-gitlab/06-deployment/ios.mdx b/docs/05-gitlab/06-deployment/ios.mdx
index 41154bc0..a50b0d0d 100644
--- a/docs/05-gitlab/06-deployment/ios.mdx
+++ b/docs/05-gitlab/06-deployment/ios.mdx
@@ -21,20 +21,19 @@ brew install fastlane
## Unity Settings
1. Switch target to iOS
-1. In `PlayerSettings -> Other Settings`
+2. In `PlayerSettings -> Other Settings`
1. Fill the field `Signing Team ID`
- 1. Ensure `Automatically Sign` is unchecked
- 1. iOS Provisioning Profile
+ 2. Ensure `Automatically Sign` is unchecked
+ 3. iOS Provisioning Profile
1. `ProfileID`: `match AppStore your_bundle_identifier` _Replace `your_bundle_identifier` by
yours_
- 1. `ProfileType`: `Distribution`
+ 2. `ProfileType`: `Distribution`
## XCode project
-Make a first iOS build using your mac from Unity, that will create an xcode project.
-Ensure you target the same path as the CI.
-Ex: if you let `BUILD_NAME: ExampleProjectName` in `.gitlab-ci.yml`, your xcode project must be at
-the root of the following path: `.\Builds\iOS\ExampleProjectName\`
+Make a first iOS build using your mac from Unity, that will create an xcode project. Ensure you
+target the same path as the CI. Ex: if you let `BUILD_NAME: ExampleProjectName` in `.gitlab-ci.yml`,
+your xcode project must be at the root of the following path: `.\Builds\iOS\ExampleProjectName\`
## App on portal
@@ -83,7 +82,7 @@ Note about `upload_to_testflight`: Change "Team" to your internal tester or remo
## Run tests locally
-Run the following command to test the build and the deployement localy:
+Run the following command to test the build and the deployment locally:
```bash
fastlane ios beta
@@ -105,8 +104,7 @@ you have to add the following files:
## Gitlab-runner - register your mac
-To automate your build with gitlab, you need to setup your mac as a gitlab runner.
-Installation:
+To automate your build with gitlab, you need to setup your mac as a gitlab runner. Installation:
```bash
sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64
@@ -124,8 +122,8 @@ Go to your project gitlab page, then go to `settings` -> `CI/CD` -> `Runners` ->
-> `Set up a specific Runner manually` -> take note of the token
[Follow these instructions](https://docs.gitlab.com/runner/register/index.html) to register your mac
-as a gitlab-runner for your specific project.
-Follow **macOS** instructions **without** sudo command for registration.
+as a gitlab-runner for your specific project. Follow **macOS** instructions **without** sudo command
+for registration.
- Tags: set `mac,ios`
- Executor: set `shell`