Docs

GitLab Tag

sourceconditiontarget

✔

✔

✗

Description

The gitlab/tag resource queries the tags of a repository hosted on GitLab, through the GitLab API rather than over the git protocol.

source

Returns the tag matching versionfilter.

condition

Tests that tag exists in the repository.

target

Not supported - a target fails with target not supported for the plugin GitLab Tags. Say so on the issue tracker if you would use one.

Note
An scm attached to a condition is ignored, with a warning. The lookup always goes to the GitLab API.
Tip
To work with tags over the git protocol instead, on any host (and to create one), use gittag.

Parameters

NameTypeDescriptionRequired
ageobject[S] Age defines the minimum or maximum age of a tag to be considered valid. It accepts a duration string (e.g., “24h”, “7d”, “3w”, “1y”). The age of a tag is its creation date, which GitLab reports as the tagger date of an annotated tag and as the commit date of a lightweight one.
    maximumstringMaximum defines the maximum age of a release to be considered valid. It accepts a duration string (e.g., “24h”, “7d”, “3w”, “1y”). Accepted time units are “h” for hours, “d” for days, “w” for weeks, “mo” for months, and “y” for years. If no unit is provided, hours are assumed.
    minimumstringMinimum defines the minimum age of a release to be considered valid. It accepts a duration string (e.g., “24h”, “7d”, “3w”, “1y”). Accepted time units are “h” for hours, “d” for days, “w” for weeks, “mo” for months, and “y” for years. If no unit is provided, hours are assumed.
ownerstring[S][C] Owner specifies repository owner
repositorystring[S][C] Repository specifies the name of a repository for a specific owner
tagstring[S] Tag defines the GitLab tag .
tokenstring

“token” defines the credential used to authenticate with GitLab

remark: A token is a sensitive information, it’s recommended to not set this value directly in the configuration file but to use an environment variable or a SOPS file.

The value can be set to {{ requiredEnv "GITLAB_TOKEN"}} to retrieve the token from the environment variable GITLAB_TOKEN or {{ .gitlab.token }} to retrieve the token from a SOPS file.

For more information, about a SOPS file, please refer to the following documentation: https://github.com/getsops/sops

urlstring

“url” defines the GitLab url to interact with

default: “gitlab.com”

usernamestring“username” defines the username used to authenticate with GitLab
versionfilterobject[S][C] VersionFilter provides parameters to specify version pattern and its type like regex, semver, or just latest.
    kindstringspecifies the version kind such as semver, regex, or latest
    patternstringspecifies the version pattern according the version kind for semver, it is a semver constraint for regex, it is a regex pattern for time, it is a date format
    regexstringspecifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
    replaceallobjectreplaceAll applies a regex replacement to version strings before filtering. This is useful for transforming versions (e.g., curl-8_15_0 to curl-8.15.0) before regex extraction.
    strictbooleanstrict enforce strict versioning rule. Only used for semantic versioning at this time

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

tag

Condition only - the tag being checked.

versionfilter

Source only. kind: semver is the usual choice for release tags. See the "Version Filtering" page.

Authentication

token authenticates against the GitLab API. It is sensitive, so read it from the environment or a SOPS file rather than writing it into the manifest:

spec:
  url: gitlab.com
  token: '{{ requiredEnv "GITLAB_TOKEN" }}'
  owner: updatecli
  repository: updatecli

Reading a public repository works without any credential.

Example

# updatecli.yaml
name: "Show Gitlab tag usage"

sources:
  default:
    name: "Get tag using versionfilter from a Gitlab repository"
    kind: "gitlab/tag"
    spec:
      # Default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli-test"
      versionfilter:
        kind: "semver"
        pattern: "~0.0"

  latest:
    name: "Get latest tag tag from a Gitlab repository"
    kind: "gitlab/tag"
    spec:
      # Default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli-test"

conditions:
  default:
    name: "Test tag '0.0.2' exist on the Gitlab repository"
    kind: "gitlab/tag"
    disablesourceinput: true
    spec:
      # Default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli"
      tag: "v0.2.0"

  sourcedefault:
    name: "Test that the tag retrieved from source 'default' exist on the Gitlab repository"
    kind: "gitlab/tag"
    sourceid: "default"
    spec:
      # Default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli"

  latest:
    name: "Test that the tag retrieved from source 'latest' exist on the Gitlab repository"
    kind: "gitlab/tag"
    sourceid: "latest"
    spec:
      # Default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli"

Links

Last updated on August 2, 2026
Prev
GitLab Release
Next
Golang