diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1125209..90d3f7d 100644 --- a/docs/SUMMARY.md +++ b/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) --- diff --git a/docs/reference/gitlab-cicd-component.md b/docs/reference/gitlab-cicd-component.md new file mode 100644 index 0000000..4f35e0c --- /dev/null +++ b/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. | `""` | 
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": + +![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)