diff --git a/README.md b/README.md index afc56d9..2a70ea4 100644 --- a/README.md +++ b/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 [ -`release-please`](https://github.com/googleapis/release-please), it streamlines the release process through GitHub Actions or GitLab CI. +
+ releaser-pleaser is a tool designed to automate versioning and changelog management for your projects. Building on the concepts of release-please, it streamlines the release process through GitHub Actions or GitLab CI.
+
version/version.go
deploy/deployment.yaml |
diff --git a/docs/tutorials/github.md b/docs/tutorials/github.md
index 83f797c..693ef65 100644
--- a/docs/tutorials/github.md
+++ b/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
diff --git a/docs/tutorials/gitlab-access-token.png b/docs/tutorials/gitlab-access-token.png
new file mode 100644
index 0000000..15d7619
--- /dev/null
+++ b/docs/tutorials/gitlab-access-token.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:31b485bbe031443c4bfa0d39514dc7e5d524925aa877848def93ee40f69a1897
+size 146496
diff --git a/docs/tutorials/gitlab-settings-merge-method.png b/docs/tutorials/gitlab-settings-merge-method.png
new file mode 100644
index 0000000..0ea01c7
--- /dev/null
+++ b/docs/tutorials/gitlab-settings-merge-method.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b853625854582a66ab2438f11e6001a88bcb276225abed536ba68617bde324db
+size 57583
diff --git a/docs/tutorials/gitlab-settings-squash.png b/docs/tutorials/gitlab-settings-squash.png
new file mode 100644
index 0000000..e0c87a4
--- /dev/null
+++ b/docs/tutorials/gitlab-settings-squash.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0ce9b9826229851e961ef55d91cb9ba91ca9ca4d955a932d9ff6b10d04788c29
+size 41048
diff --git a/docs/tutorials/gitlab.md b/docs/tutorials/gitlab.md
new file mode 100644
index 0000000..b38c807
--- /dev/null
+++ b/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":
+
+
+
+In the "Squash commits when merging" section select "Require":
+
+
+
+## 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.
+
+
+
+## 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)