Merge branch 'main' into main

Author: ejnarvala

docs/03-github/02-activation.mdx

@@ -1,56 +1,81 @@
+import unityHubPreferencesLicensesAddButton from '/assets/images/unity-hub-preferences-licenses-add-button.png';
+
 # Activation
 
-All actions use a Unity installation, which needs to be activated.
+All Unity actions require activation.
+
+### Choosing the Right Activation Method
+
+To activate Unity, select the method that matches your license type:
 
-Unity differentiates their methods between `personal` and `professional` licenses.
+- If you're using the **free version**, follow the steps for a
+  [Personal License](#personal-license).
+- If you're using the **paid version**, such as Unity Plus or Pro, refer to the instructions for a
+  [Professional License](#professional-license).
+- For organizations using a **license server**, you can provide the server's URL as detailed in the
+  [License Server](#license-server) section.
 
-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](#personal-license) or a
-[professional license](#professional-license). Alternatively you can provide the url to a
-[License server](#license-server).
+Choose the appropriate method to ensure your Unity environment is activated and ready for use.
 
 ## Personal license
 
-Follow these steps if you are using a free version of Unity.
+Follow these steps if you are using the free version of Unity.
 
-> _**Note:** Do NOT follow the steps for the personal license if you have a professional license._
+> _**Note:** Do not follow the steps for the personal license if you have a professional license._
+
+### Mental Model
+
+1. **Activate the license locally**: Use Unity Hub to create a `.ulf` license file linked to your
+   Unity account.
+2. **Add the license to GitHub**: Store the `.ulf` file and Unity credentials as GitHub secrets for
+   use in CI builds.
 
-#### Mental model
+### Setting Up Your Unity License
 
-1. Activate a license for use on Github via a local machine
-2. Set the license as a secret
+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:
 
-#### Activating a license file
+   - `Unity Hub` > `Preferences` > `Licenses` and click the `Add` button
+   - Select **Get a free personal license**.
 
-1. Install [Unity Hub](https://unity.com/download) on your local machine.
-2. Log into Unity Hub with the Unity account that you are using for CI. Make sure you log into the
-   correct account or you may not activate the correct license.
-3. When prompted, activate your personal license. If you are not prompted, go to `Unity Hub` >
-   `Preferences` > `Licenses` > `Add` and choose `Get a free personal license`. You do not need to
-   install an editor on your local machine.
-4. Depending on the host you are using, find the `.ulf` file which is your Unity license in the
-   following paths:
+   :::info Ensure File Creation
+
+   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.
+
+   <img
+     src={unityHubPreferencesLicensesAddButton}
+     alt="Unity Hub interface showing the Preferences window with the Licenses tab selected and the Add button highlighted"
+   />
+
+4. **Locate the `.ulf` file**: Depending on your operating system, the Unity license file will be
+   located in one of these paths:
 
    - Windows: `C:\ProgramData\Unity\Unity_lic.ulf`
    - Mac: `/Library/Application Support/Unity/Unity_lic.ulf`
    - Linux: `~/.local/share/unity3d/Unity/Unity_lic.ulf`
 
-   If you have issues locating the file, ensure you've logged into Unity Hub AND activated your
-   license. Otherwise the file will not be present. Keep in mind these folders might be hidden by
-   default, you may need to reveal hidden files to see them.
+   If you have trouble locating the `.ulf` file, follow these steps:
 
-   > **Note:** The host platform you use to activate the license does not matter. You only need to
-   > get the ulf from the platform that is most convenient to you. For example, using Windows to
-   > activate your license and building on Ubuntu on Github is perfectly fine.
+   - **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.
 
-5. Open `Github` > `<Your repository>` > `Settings` > `Secrets and Variables` > `Actions`.
-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)_
-7. Return your personal license in Unity Hub on the local machine you used to ensure you aren't
-   using up one of the seats. You can do this by going to `Unity Hub` > `Preferences` > `Licenses`
-   and choose `Return license` on the Personal license listed in the window.
+5. **Add Secrets to GitHub**: Navigate to `GitHub` > `<Your repository>` > `Settings` >
+   `Secrets and Variables` > `Actions`. Then, create the following secrets:
+
+   - **`UNITY_LICENSE`**: Copy and paste the contents of your `.ulf` license file
+   - **`UNITY_EMAIL`**: Enter the email address associated with your Unity account
+   - **`UNITY_PASSWORD`**: Enter the password for your Unity account
 
 **GameCI does not acquire nor store your Unity email, password, or license file contents. They are
 required for activating the license during build and test steps.**

docs/03-github/04-builder.mdx

@@ -644,10 +644,10 @@ using `sshPublicKeysDirectoryPath` and setting the `GIT_CONFIG_EXTENSIONS` envir
 ```yaml
 - uses: webfactory/ssh-agent@v0.8.0
   with:
-  ssh-private-key: |
-    ${{ secrets.FIRST_KEY }}
-    ${{ secrets.NEXT_KEY }}
-    ${{ secrets.ANOTHER_KEY }}
+    ssh-private-key: |
+      ${{ secrets.FIRST_KEY }}
+      ${{ secrets.NEXT_KEY }}
+      ${{ secrets.ANOTHER_KEY }}
 
 - name: Prepare SSH config for unity builder
   run: |

docs/05-gitlab/01-getting-started.mdx

@@ -8,10 +8,9 @@ gitlab using gitlab-ci.
 ## Overall steps
 
 1. Understand how [gitlab-ci](https://docs.gitlab.com/ce/ci/) works.
-2. Configure a license for Unity.
-3. Add build scripts and integrations in your Unity project
-4. Set up a gitlab-ci pipeline for your project.
-5. Result: Accept merge requests with more confidence.
+2. Add build scripts and gitlab-ci integration in your Unity project
+3. Configure a license for Unity.
+4. Successfully build and test your Unity project 🎉
 
 ## First time using Gitlab CI?
 
@@ -22,55 +21,96 @@ Any subsequent steps assume you have read the above.
 
 ## Supported versions
 
-The [unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) is
-based on [unity3d](https://github.com/game-ci/docker/) docker images from
-[game-ci](https://github.com/game-ci). Any version in the
-[docker hub `unityci/editor` tags list](https://hub.docker.com/r/unityci/editor/tags) can be used to
-test and build projects.
+The [unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/) uses
+[unity3d docker images](https://github.com/game-ci/docker/) published by
+[game-ci](https://github.com/game-ci).
 
-It's generally considered good practice to use the same Unity version for your CI/CD setup as you do
-to develop your project.
+:::tip
+
+Before proceeding, verify that your Unity version is supported by checking the
+[Docker > Versions page](/docs/docker/versions).
+
+:::
+
+It is generally considered good practice to use the same Unity version for your CI/CD setup as you
+do to develop your project. Our Gitlab CI configuration will automatically detect and use the
+correct Unity version for your project.
 
 ## Video tutorial
 
 <Video url="https://www.youtube-nocookie.com/embed/k0NcedDzEqA" />
 
-## Setting up gitlab-ci for your Unity project
+:::caution
+
+The video (recorded with Unity 2020.x) is slightly outdated, but the general concepts are still the
+same. 👍
+
+- The activation process has changed a bit since then.
+- Docker images have been updated
+- The `.gitlab-ci.yml` file uses different variables now.
+
+:::
+
+### Steps to Set Up Unity CI/CD with GitLab
+
+#### 1. Clone the Example Repository
+
+Start by cloning the GameCI example project provided by GameCI to use its configuration files.
+
+```bash
+git clone https://gitlab.com/game-ci/unity3d-gitlab-ci-example.git
+```
+
+#### 2. (Optional) Checkout a Specific Version
+
+If you want to use a specific version of the example project, checkout the desired tag.
+
+```bash
+cd unity3d-gitlab-ci-example
+git checkout v4.0.0
+cd ..
+```
+
+:::info
+
+See [example project's release](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/releases) for
+stable versions.
 
-### I don't have a Unity project yet
+:::
 
-1. Fork
-   [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/)
-1. Clone the fork you just created locally
-1. Continue to activation instructions
+#### 3. Navigate to Your Unity Project
 
-### I already have my own Unity project
+Replace `your-unity-project` with the actual name of your Unity project folder.
 
-1. Clone
-   [the unity3d-gitlab-ci-example project](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/)
-1. Copy
-   [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)
-   to the root of your repository,
-   [`Assets/Scripts/Editor/BuildCommand.cs`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/Assets/Scripts/Editor/BuildCommand.cs)
-   and [`ci` folder](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/ci) to your
-   project:
+```bash
+cd your-unity-project
+```
 
-Assuming you've cloned the example project in the parent folder of your project, and your Unity
-project is at the root of your repository, execute these commands from the root folder of your
-project:
+#### 4. Create Necessary Directories
+
+Create the required directories in your Unity project to hold CI-related files.
 
 ```bash
 mkdir -p Assets/Scripts/Editor/
+```
+
+#### 5. Copy Required Files
+
+Copy the necessary CI configuration and scripts from the example project to your Unity project.
+
+```bash
 cp ../unity3d-gitlab-ci-example/.gitlab-ci.yml ./
 cp -r ../unity3d-gitlab-ci-example/ci ./
 cp ../unity3d-gitlab-ci-example/Assets/Scripts/Editor/BuildCommand.cs ./Assets/Scripts/Editor/
 ```
 
-1. Open and edit the
-   [`.gitlab-ci.yml`](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml)
-   you copied to your project and update
-   [the variables](https://gitlab.com/game-ci/unity3d-gitlab-ci-example/-/blob/main/.gitlab-ci.yml#L7-13)
-   with the versions you need. Your Unity project version can be found in
-   `ProjectSettings/ProjectVersion.txt`.
-1. If your Unity project is not at the root of your repository, also update UNITY_DIR variable.
-1. Continue to activation instructions
+#### Final Note:
+
+If your Unity project is not at the root of your repository, update the paths accordingly in the
+commands above and in the `.gitlab-ci.yml` file. Adjust the `UNITY_DIR` variable in `.gitlab-ci.yml`
+to point to your project directory.
+
+## Proceed to activation
+
+That’s It! You're one step away from having automated builds and tests for your Unity project.
+Proceed to the [Activation](./02-activation.mdx) guide.