Merge branch 'fforster/semantic-release-docs' into 'main'

docs(semantic-release): Add a "setup guide" section.

See merge request gitlab-com/gl-infra/common-ci-tasks!575

semantic-release.md

@@ -8,30 +8,81 @@ Further Reading:
 1. [Automate Semantic Versioning with Conventional Commits](https://medium.com/@jsilvax/automate-semantic-versioning-with-conventional-commits-d76a9f45f2fa).
 1. [Basic Guide to Semantic Release](https://levelup.gitconnected.com/basic-guide-to-semantic-release-9e2aa7834e4b)
-* Default Stage: `release` (make sure this stage is one of the last in your pipeline)
-
-You will also need a file called `.releaserc.json` included in your project. Copy this one if you are unsure.
-
-```json
-{
-  "branches": ["main"],
-  "plugins": [
-    [
-      "@semantic-release/commit-analyzer",
-      {
-        "preset": "conventionalcommits"
+## Setup guide
+
+### Happy path
+
+1.  Manage the GitLab project in [gl-infra/infra-mgmt](https://gitlab.com/gitlab-com/gl-infra/infra-mgmt/):
+
+    ```hcl
+    module "project_example" {
+      source  = "ops.gitlab.net/gitlab-com/project/gitlab"
+      version = "3.0.1" # renovate:managed
+
+      common_ci_tasks = {
+        enabled = true
       }
-    ],
-    [
-      "@semantic-release/release-notes-generator",
-      {
-        "preset": "conventionalcommits"
+
+      vault = {
+        enabled   = true
+        # …
       }
-    ],
-    "@semantic-release/gitlab"
-  ]
-}
-```
+
+      # …
+    }
+    ```
+
+    This automatically creates a [Project Access Token](#project-access-token) for Semantic Release and stores it in Vault.
+1.  Use `copier` to initialize the repository:
+
+    ```shell
+    copier copy https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git new-repo/
+    ```
+
+    This creates a `.gitlab-ci.yml` file that includes `semantic-release.yml` via `templates/standard.yml`.
+
+Done :tada:
+
+### Manual setup
+
+1.  Create a [Project Access Token](#project-access-token) for Semantic Release.
+1.  Store the *Project Access Token* in [Vault](#vault) or a [CI variable](#ci-variable).
+1.  Create a `.releaserc.json` file in your project. Copy this one if you are unsure.
+
+    ```json
+    {
+      "branches": ["main"],
+      "plugins": [
+        [
+          "@semantic-release/commit-analyzer",
+          {
+            "preset": "conventionalcommits"
+          }
+        ],
+        [
+          "@semantic-release/release-notes-generator",
+          {
+            "preset": "conventionalcommits"
+          }
+        ],
+        "@semantic-release/gitlab"
+      ]
+    }
+    ```
+1.  Ensure your `.gitlab-ci.yml` file includes a `release` stage. This stage should be one of the last in your pipeline, after the build stage. You can provide a different stage name if you don't want to use `release`.
+1.  Include `semantic-release.yml` from your `.gitlab-ci.yml` file:
+
+    ```yaml
+    include:
+      # Analyze commits to determine whether to cut a release
+      # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/semantic-release.md
+      - project: 'gitlab-com/gl-infra/common-ci-tasks'
+        ref: v2.11.0  # renovate:managed
+        file: semantic-release.yml
+        #inputs:
+        #  stage: release
+        #  vault: access_tokens/${VAULT_SECRETS_PATH}/semantic-release/token@ci
+    ```
 ## Project Access Token
@@ -50,10 +101,10 @@ Projects managed by [gl-infra/infra-mgmt](https://gitlab.com/gitlab-com/gl-infra
 ```hcl
 module "project_example" {
   source  = "ops.gitlab.net/gitlab-com/project/gitlab"
-  version = "2.2.0"
-  common_access_tokens = {
-    semantic_release = true
+  version = "3.0.1" # renovate:managed
+  common_ci_tasks = {
+    enabled = true
   }
   vault = {
@@ -83,7 +134,7 @@ Store the secret in Vault, typically in the `ci` "engine", and provide a path to
 Create a protected, masked `SEMANTIC_RELEASE_GITLAB_TOKEN` environment variable through the CI/CD Variables settings.
-This could be a group token if appropriate. If the `SEMANTIC_RELEASE_GITLAB_TOKEN` does not exist, `GITLAB_TOKEN` will be used.
+This could be a group token if appropriate.
 ## Example CI include