diff --git a/.github/workflows/mirror.yaml b/.github/workflows/mirror.yaml index c57187e..76c963b 100644 --- a/.github/workflows/mirror.yaml +++ b/.github/workflows/mirror.yaml @@ -15,6 +15,8 @@ jobs: with: # Need all to fetch all tags so we can push them fetch-depth: 0 + # Required so they can be pushed too + lfs: true - name: Add Remote env: diff --git a/CHANGELOG.md b/CHANGELOG.md index d753e0a..a3a315d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,19 @@ ## [v0.4.0](https://github.com/apricote/releaser-pleaser/releases/tag/v0.4.0) +### ✨ Highlights + +#### GitLab Support + +You can now use `releaser-pleaser` with projects hosted on GitLab.com and self-managed GitLab installations. Check out the new [tutorial](https://apricote.github.io/releaser-pleaser/tutorials/gitlab.html) to get started. + ### Features - add support for GitLab repositories (#49) - add shell to container image (#59) - **gitlab**: add CI/CD component (#55) - **changelog**: omit version heading in forge release notes +- **gitlab**: support self-managed instances (#75) ### Bug Fixes 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. +

+ +

+ Badge: Documentation + Badge: Stable Release + Badge: License GPL-3.0 +

## 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 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1125209..d001c2d 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 @@ -16,13 +16,14 @@ - [Customizing Release Notes](guides/release-notes.md) - [Pre-releases](guides/pre-releases.md) - [Workflow Permissions on GitHub](guides/github-workflow-permissions.md) +- [Updating arbitrary files](guides/updating-arbitrary-files.md) # Reference - [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/guides/updating-arbitrary-files.md b/docs/guides/updating-arbitrary-files.md new file mode 100644 index 0000000..d4b65bf --- /dev/null +++ b/docs/guides/updating-arbitrary-files.md @@ -0,0 +1,63 @@ +# Updating arbitrary files + +In some situations it makes sense to have the current version committed in files in the repository: + +- Documentation examples +- A source-code file that has the version for user agents and introspection +- Reference to a container image tag that is built from the repository + +`releaser-pleaser` can automatically update these references in the [Release PR](../explanation/release-pr.md). + +## Markers + +The line that needs to be updated must have the marker `x-releaser-pleaser-version` somewhere after the version that should be updated. + +For example: + +```go +// version/version.go + +package version + +const Version = "v1.0.0" // x-releaser-pleaser-version +``` + +## Extra Files + +You need to tell `releaser-pleaser` which files it should update. This happens through the CI-specific configuration. + +### GitHub Action + +In the GitHub Action you can set the `extra-files` input with a list of the files. They need to be formatted as a single multi-line string with one file path per line: + +```yaml +jobs: + releaser-pleaser: + steps: + - uses: apricote/releaser-pleaser@v0.4.0 + with: + extra-files: | + version.txt + version/version.go + docker-compose.yml +``` + +### GitLab CI/CD Component + +In the GitLab CI/CD Component you can set the `extra-files` input with a list of files. They need to be formatted as a single multi-line string with one file path per line: + +```yaml +include: + - component: $CI_SERVER_FQDN/apricote/releaser-pleaser/run@v0.4.0 + inputs: + extra-files: | + version.txt + version/version.go + docker-compose.yml +``` + +## Related Documentation + +- **Reference** + - [GitHub Action](../reference/github-action.md#inputs) + - [GitLab CI/CD Component](../reference/gitlab-cicd-component.md#inputs) 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..2e5ed72 --- /dev/null +++ b/docs/tutorials/gitlab.md @@ -0,0 +1,94 @@ +# 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. + +
+ +If you want to use `releaser-pleaser` on a self-managed GitLab instance, you need to mirror the GitLab.com component to your instance. See the official [GitLab documentation for details](https://docs.gitlab.com/ee/ci/components/#use-a-gitlabcom-component-in-a-self-managed-instance). + +
+ +## 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) diff --git a/internal/forge/gitlab/gitlab.go b/internal/forge/gitlab/gitlab.go index 1394898..f77b324 100644 --- a/internal/forge/gitlab/gitlab.go +++ b/internal/forge/gitlab/gitlab.go @@ -24,8 +24,14 @@ const ( PRStateOpen = "opened" PRStateMerged = "merged" PRStateEventClose = "close" - EnvAPIToken = "GITLAB_TOKEN" // nolint:gosec // Not actually a hardcoded credential - EnvProjectPath = "CI_PROJECT_PATH" + + EnvAPIToken = "GITLAB_TOKEN" // nolint:gosec // Not actually a hardcoded credential + + // The following vars are from https://docs.gitlab.com/ee/ci/variables/predefined_variables.html + + EnvAPIURL = "CI_API_V4_URL" + EnvProjectURL = "CI_PROJECT_URL" + EnvProjectPath = "CI_PROJECT_PATH" ) type GitLab struct { @@ -36,19 +42,23 @@ type GitLab struct { } func (g *GitLab) RepoURL() string { + if g.options.ProjectURL != "" { + return g.options.ProjectURL + } + return fmt.Sprintf("https://gitlab.com/%s", g.options.Path) } func (g *GitLab) CloneURL() string { - return fmt.Sprintf("https://gitlab.com/%s.git", g.options.Path) + return fmt.Sprintf("%s.git", g.RepoURL()) } func (g *GitLab) ReleaseURL(version string) string { - return fmt.Sprintf("https://gitlab.com/%s/-/releases/%s", g.options.Path, version) + return fmt.Sprintf("%s/-/releases/%s", g.RepoURL(), version) } func (g *GitLab) PullRequestURL(id int) string { - return fmt.Sprintf("https://gitlab.com/%s/-/merge_requests/%d", g.options.Path, id) + return fmt.Sprintf("%s/-/merge_requests/%d", g.RepoURL(), id) } func (g *GitLab) GitAuth() transport.AuthMethod { @@ -393,20 +403,41 @@ func gitlabMRToReleasePullRequest(pr *gitlab.MergeRequest) *releasepr.ReleasePul func (g *Options) autodiscover() { // Read settings from GitLab-CI env vars + if apiURL := os.Getenv(EnvAPIURL); apiURL != "" { + g.APIURL = apiURL + } + if apiToken := os.Getenv(EnvAPIToken); apiToken != "" { g.APIToken = apiToken } + if projectURL := os.Getenv(EnvProjectURL); projectURL != "" { + g.ProjectURL = projectURL + } + if projectPath := os.Getenv(EnvProjectPath); projectPath != "" { g.Path = projectPath } + +} + +func (g *Options) ClientOptions() []gitlab.ClientOptionFunc { + options := []gitlab.ClientOptionFunc{} + + if g.APIURL != "" { + options = append(options, gitlab.WithBaseURL(g.APIURL)) + } + + return options } type Options struct { forge.Options - Path string + ProjectURL string + Path string + APIURL string APIToken string } @@ -414,7 +445,7 @@ func New(log *slog.Logger, options *Options) (*GitLab, error) { log = log.With("forge", "gitlab") options.autodiscover() - client, err := gitlab.NewClient(options.APIToken) + client, err := gitlab.NewClient(options.APIToken, options.ClientOptions()...) if err != nil { return nil, err }