# GitLab Release<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10004;
|===

== Description

The `gitlab/release` resource works with the releases published on a GitLab repository.

**source**::
Returns the release matching `versionfilter`.

**condition**::
Tests that a release exists for the repository.

**target**::
**Creates the release** when one does not already exist for the tag. This is one of the few resources that publish something rather than edit a file.

NOTE: An `scm` attached to a condition is ignored, with a warning. The lookup always goes to the GitLab API.

== Parameters

{{< resourceparameters "sources" "gitlab/release" >}}

`owner` and `repository` are mandatory. `url` defaults to `gitlab.com`. Set it for a self-managed instance.

=== Creating a release

These fields apply to a target, and two of them have defaults that are easy to trip over:

[cols="1,3",options=header]
|===
| Field | Behaviour
| `tag` | The tag the release points at. **Defaults to the source output.**
| `title` | The release title. **Defaults to the tag**, so an untitled release is named after its version.
| `commitish` | The branch or commit the tag is created from. **Defaults to `main`**, with the warning `No commitish provided, fallback to branch "main"` - wrong on any repository whose default branch is `master` or `develop`, so set it explicitly.
| `description` | The release body.
| `draft` | Publish as a draft.
| `prerelease` | Flag the release as a pre-release.
|===

A release that already exists is left untouched (the target neither updates its title nor its description).

== Authentication

`token` authenticates against the GitLab API. It is sensitive, so read it from the environment or a link:https://github.com/getsops/sops[SOPS] file rather than writing it into the manifest:

[source,yaml]
----
spec:
  url: gitlab.com
  token: '{{ requiredEnv "GITLAB_TOKEN" }}'
  owner: updatecli
  repository: updatecli
----

A source or condition on a public repository needs no credential. Creating a release needs write access.

== Example

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/gitlab/release/updatecli.d/default.yaml">}}
----

== Links

* link:/docs/plugins/resource/gitlabbranch/[The `gitlab/branch` resource]
* link:/docs/plugins/resource/gitlabtag/[The `gitlab/tag` resource]
* link:/docs/plugins/scm/gitlab/[The `gitlab` scm] - to clone and push