GitLab CI Documentation for v4.0.0 Release - Environment Variable Changes for Unity License Activation

[GabLeRoux]

The GitLab CI Unity3D example project has recently been updated with breaking changes in version 4.0.0. These changes affect how Unity licenses are activated and the required environment variables for the CI pipeline. The documentation on the game.ci website needs to be updated to reflect these changes to ensure that users can continue to activate Unity licenses without issues.

Related website page to update:

• https://game.ci/docs/gitlab/activation
  We should get closer to the following documentation:
• https://game.ci/docs/github/activation/

Changes to Be Updated in the Documentation:

1. Unity License Activation Update:

   • The UNITY_USERNAME variable has been replaced with UNITY_EMAIL.
   • The UNITY_SERIAL environment variable has been made mandatory for activation and must be extracted from the Unity license file (.ulf). This might be a temporary change until we have a better solution
   • Breaking change: The old get_activation_file.sh script has been removed. Users should now use the updated activation process, which involves Unity's blank project for license verification.
   • Documentation should reflect these new changes and include updated instructions for retrieving and setting up the necessary environment variables (UNITY_EMAIL, UNITY_PASSWORD, UNITY_SERIAL).

2. CI/CD Configuration Changes:

   • The .gitlab-ci.yml example configuration should be updated to reflect the new environment variables and the updated license activation process.
   • Users of earlier versions should be instructed to update the ci folder containing the different shell script for activation and returning licenses.

3. Docker Image Updates:

   • Ensure the documentation reflects the fact that the project now supports v3 Docker images.
   • Provide guidance on how to adjust existing CI configurations to prevent errors caused by using outdated images.

4. New Instructions for Unity License File:

   • Detailed steps on how to extract the UNITY_SERIAL from the .ulf file should be added.
   • Update instructions for creating and setting the new environment variables (UNITY_EMAIL, UNITY_PASSWORD, UNITY_SERIAL) in GitLab's CI/CD settings.

Suggested Documentation Updates:

1. Activation Section:

   • Update instructions to specify that UNITY_EMAIL, UNITY_PASSWORD, and UNITY_SERIAL are now required as environment variables.
   • Provide updated steps for retrieving and configuring these variables.
   • Update the section where users configure their Unity credentials in GitLab CI/CD settings to reflect the new environment variable names.

2. License Handling:

   • Clarify that Unity’s new activation mechanism requires the serial to be extracted from the .ulf file using a new script and add these steps to the documentation.

[Rodot]

Thanks for the amazing work 🙏

I couldn't figure how to extract the license from the .ulf file, in the ulf there is a SerialMasked field but the end of it is masked by XXXX, eg <SerialMasked Value="F4-UY9Q-ME8T-D9ZQ-5BEW-XXXX"/>. You mention that a new script is required to extract it, is this script available somewhere ?

Edit: Since I'm trying to get it to work on gitlab, I could do a PR for the documentation once I get it working ?

[GabLeRoux]

Hey there, pull-requests are welcome indeed. concerning the serial, I've written instructions in the release here:
https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/releases/v4.0.0

Instructions are like this:

Retrieving Unity License File:

Follow these steps to retrieve and decode your Unity license:

1. Activate a Unity license using Unity Hub on your local machine. If the file is not present, you must request a new license with the Add button even if a license is shown in the UI.
   
2. Locate the .ulf file as detailed here.
3. Extract the serial from Unity_lic.ulf:

On Linux and macOS:

cat Unity_lic.ulf | grep DeveloperData | sed -E 's/.*Value="([^"]+)".*/\1/' | base64 --decode

On Windows, you can use the following powershell command:

Get-Content Unity_lic.ulf | Select-String -Pattern 'DeveloperData' | ForEach-Object {
    if ($_ -match 'Value="([^"]+)"') {
        $base64String = $matches[1]
        [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($base64String))
    }
}

[GabLeRoux]

I'm about to send a pull-request to update the GitHbu actions activation section as well to make it clear that we need to click the Add button as described in #469