Improve GameCI Gitlab Docs (#492)

* Improve Gitlab related documentation and update for recent releases - Added caution message about the slightly outdated video tutorial. - Updated information on setting up GitLab CI for Unity projects. - Included instructions for extracting and storing Unity serial for Personal licenses. - Added steps for using a License Server with GitLab CI. - Updated debugging activation locally with Docker. - Added next steps after activating the Unity license in GitLab CI. * Improve verification steps and wording in getting started * Fix file path in verification * Remove comment about customizing unity version * Simplify overall steps * Replace e.g. with 'format:' Co-authored-by: Webber Takken <[email protected]> * Use commitizen style for commit * Update docs/05-gitlab/02-activation.mdx Co-authored-by: Gabriel Le Breton <[email protected]> * Apply some review recommendations from coderabbitai * docs: Split the setup into smaller code blocks * docs: Fix typos in deployment scripts * docs: Apply coderabbitai recommendations to Getting Started * docs: Apply some recommendations to docs --------- Co-authored-by: Webber Takken <[email protected]>
game-ci · Jan 10, 2025 · 92691c9 · 92691c9
1 parent e2abe5a
commit 92691c9
Show file tree

Hide file tree

Showing 5 changed files with 303 additions and 201 deletions.
diff --git a/docs/05-gitlab/01-getting-started.mdx b/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.