docs: GitLab tutorial and CI/CD component reference (#72)

README.md

@@ -1,7 +1,14 @@
 # releaser-pleaser
 
-`releaser-pleaser` is a tool designed to automate versioning and changelog management for your projects. Building on the concepts of [
+<p align="center">
-`release-please`](https://github.com/googleapis/release-please), it streamlines the release process through GitHub Actions or GitLab CI.
+  <code>releaser-pleaser</code> is a tool designed to automate versioning and changelog management for your projects. Building on the concepts of <a href="https://github.com/googleapis/release-please"><code>release-please</code></a>, it streamlines the release process through GitHub Actions or GitLab CI.
+</p>
+
+<p align="center">
+  <a href="https://apricote.github.io/releaser-pleaser" target="_blank"><img src="https://img.shields.io/badge/Documentation-brightgreen?style=flat-square" alt="Badge: Documentation"/></a>
+  <a href="https://github.com/apricote/releaser-pleaser/releases" target="_blank"><img src="https://img.shields.io/github/v/release/apricote/releaser-pleaser?sort=semver&display_name=release&style=flat-square&color=green" alt="Badge: Stable Release"/></a>
+  <img src="https://img.shields.io/badge/License-GPL--3.0-green?style=flat-square" alt="Badge: License GPL-3.0"/>
+</p>
 
 ## Features
 
@@ -15,10 +22,6 @@
 
 `releaser-pleaser` simplifies release management, allowing maintainers to focus on development while ensuring consistent and well-documented releases.
 
-## Status
-
-This project is still under active development. You can not reasonably use it right now and not all features advertised above work. Keep your eyes open for any releases.
-
 ## Relation to `release-please`
 
 After using

docs/SUMMARY.md

@@ -5,7 +5,7 @@
 # Tutorials
 
 - [Getting started on GitHub](tutorials/github.md)
-- [Getting started on GitLab]()
+- [Getting started on GitLab](tutorials/gitlab.md)
 
 # Explanation
 
@@ -22,7 +22,7 @@
 - [Glossary](reference/glossary.md)
 - [Pull Request Options](reference/pr-options.md)
 - [GitHub Action](reference/github-action.md)
-- [GitLab CI]()
+- [GitLab CI/CD Component](reference/gitlab-cicd-component.md)
 
 ---
 

docs/reference/gitlab-cicd-component.md

@@ -0,0 +1,23 @@
+# GitLab CI/CD Component
+
+## Reference
+
+The CI/CD component is available as `$CI_SERVER_FQDN/apricote/releaser-pleaser/run` on gitlab.com.
+
+It is being distributed through the CI/CD Catalog: [apricote/releaser-pleaser](https://gitlab.com/explore/catalog/apricote/releaser-pleaser).
+
+## Versions
+
+The `apricote/releaser-pleaser` action is released together with `releaser-pleaser` and they share the version number.
+
+The component does not support floating tags (e.g. `v1`) right now ([#31](https://github.com/apricote/releaser-pleaser/issues/31)). You have to use the full version or commit SHA instead: `apricote/releaser-pleaser@v0.4.0`.
+
+## Inputs
+
+The following inputs are supported by the component.
+
+| Input                  | Description                                               | Default |                                                              Example |
+| ---------------------- | :-------------------------------------------------------- | ------: | -------------------------------------------------------------------: |
+| `branch`               | This branch is used as the target for releases.           |  `main` |                                                             `master` |
+| `token` (**required**) | GitLab access token for creating and updating release PRs |         |                                            `$RELEASER_PLEASER_TOKEN` |
+| `extra-files`          | List of files that are scanned for version references.    |    `""` | <pre><code>version/version.go<br>deploy/deployment.yaml</code></pre> |

docs/tutorials/github.md

@@ -1,6 +1,6 @@
-# GitHub
+# Getting started on GitHub
 
-In this tutorial we show how to install `releaser-pleaser` in your GitHub project.
+In this tutorial you will learn how to set up `releaser-pleaser` in your GitHub project with GitHub Actions.
 
 ## 1. Repository Settings
 
@@ -52,7 +52,7 @@ jobs:
       pull-requests: write
     steps:
       - name: releaser-pleaser
-        uses: apricote/releaser-pleaser@v0.2.0
+        uses: apricote/releaser-pleaser@v0.4.0
 ```
 
 ## 3. Release Pull Request

docs/tutorials/gitlab-access-token.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:31b485bbe031443c4bfa0d39514dc7e5d524925aa877848def93ee40f69a1897
+size 146496

docs/tutorials/gitlab-settings-merge-method.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b853625854582a66ab2438f11e6001a88bcb276225abed536ba68617bde324db
+size 57583

docs/tutorials/gitlab-settings-squash.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0ce9b9826229851e961ef55d91cb9ba91ca9ca4d955a932d9ff6b10d04788c29
+size 41048

docs/tutorials/gitlab.md

@@ -0,0 +1,88 @@
+# Getting started on GitLab
+
+In this tutorial you will learn how to set up `releaser-pleaser` in your GitLab project with GitLab CI.
+
+> In `releaser-pleaser` documentation we mostly use "Pull Request" (GitHub wording) instead of "Merge Request" (GitLab wording). The GitLab-specific pages are an exception and use "Merge Request".
+
+## 1. Project Settings
+
+### 1.1. Merge Requests
+
+`releaser-pleaser` requires _Fast-forward merges_ and _squashing_. With other merge options it can not reliably find the right merge request for every commit on `main`.
+
+Open your project settings to page _Merge Requests_:
+
+> `https://gitlab.com/YOUR-PATH/YOUR-PROJECT/-/settings/merge_requests`
+
+In the "Merge method" section select "Fast-forward merge":
+
+![Screenshot of the required merge method settings](./gitlab-settings-merge-method.png)
+
+In the "Squash commits when merging" section select "Require":
+
+![Screenshot of the required squash settings](./gitlab-settings-squash.png)
+
+## 2. API Access Token
+
+`releaser-pleaser` uses the GitLab API to create the [release merge request](../explanation/release-pr.md) and subsequent releases for you. The default `GITLAB_TOKEN` available in CI jobs does not have enough permissions for this, so we need to create an Access Token and make it available in a CI variable.
+
+## 2.1. Create Project Access Token
+
+Open your project settings to page _Access tokens_:
+
+> `https://gitlab.com/YOUR-PATH/YOUR-PROJECT/-/settings/access_tokens`
+
+Create a token with these settings:
+
+- **Name**: `releaser-pleaser`
+- **Role**: `Maintainer`
+- **Scopes**: `api`, `read_repository`, `write_repository`
+
+Copy the created token for the next step.
+
+![Screenshot of the access token settings](./gitlab-access-token.png)
+
+## 2.2. Save token in CI variable
+
+Open your project settings to page _CI/CD_:
+
+> `https://gitlab.com/YOUR-PATH/YOUR-PROJECT/-/settings/ci_cd`
+
+In the section "Variables" click on the "Add variable" button to open the form for a new variable. Use these settings to create the new variable:
+
+- **Type**: Variable
+- **Visibility**: Masked
+- **Flags**: Uncheck "Protect variable" if your `main` branch is not protected
+- **Key**: `RELEASER_PLEASER_TOKEN`
+- **Value**: The project access token from the previous step
+
+## 3. GitLab CI/CD
+
+`releaser-pleaser` is published as a [GitLab CI/CD Component](https://docs.gitlab.com/ee/ci/components/): https://gitlab.com/explore/catalog/apricote/releaser-pleaser
+
+Create or open your `.gitlab-ci.yml` and add the following include to your configuration:
+
+```yaml
+stages: [build]
+
+include:
+  - component: $CI_SERVER_FQDN/apricote/releaser-pleaser/run@v0.4.0-beta.1
+    inputs:
+      token: $RELEASER_PLEASER_TOKEN
+```
+
+> You can set the `stage` input if you want to run `releaser-pleaser` during a different stage.
+
+## 4. Release Merge Request
+
+Once the `releaser-pleaser` job runs for the first time, you can check the logs to see what it did.
+If you have releasable commits since the last tag, `releaser-pleaser` opens a release merge request for the proposed release.
+
+Once you merge this merge request, `releaser-pleaser` automatically creates a Git tag and GitLab Release with the proposed version and changelog.
+
+## Related Documentation
+
+- **Explanation**
+  - [Release Pull Request](../explanation/release-pr.md)
+- **Reference**
+  - [GitLab CI/CD Component](../reference/gitlab-cicd-component.md)