Docs

GitLab Branch

sourceconditiontarget

✔

✔

✗

Description

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

source

Returns the branch matching versionfilter (typically the highest release/x.y).

condition

Tests that branch exists in the repository.

target

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

Important

Unlike most resources, which merely log a warning, a condition with an scm attached is rejected here:

Condition not supported for the plugin GitLab branch

Drop the scmid; the lookup always goes to the GitLab API.

Tip
To work with branches over the git protocol instead, on any host, use gitbranch.

Parameters

NameTypeDescriptionRequired
ageobject[S] Age defines the minimum or maximum age of a branch to be considered valid. It accepts a duration string (e.g., “24h”, “7d”, “3w”, “1y”). The age of a branch is the committer date of its latest commit.
    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.
branchstring[C] Branch specifies the branch name
ownerstring[S][C] Owner specifies repository owner
repositorystring[S][C] Repository specifies the name of a repository for a specific owner
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] 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.

branch

Condition only - the branch being checked.

versionfilter

Source only. 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: "Demo Gitlab branch"

sources:
  default:
    kind: "gitlab/branch"
    spec:
      # default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli"
      branch: main

conditions:
  default:
    name: Show condition usage without source input
    kind: "gitlab/branch"
    disablesourceinput: true
    spec:
      # default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli"
      branch: "main"

  sourcedefault:
    name: Show condition using branch name fetch from source input
    kind: "gitlab/branch"
    sourceid: "default"
    spec:
      # default to gitlab.com
      # url: "gitlab.com"
      owner: "olblak"
      repository: "updatecli-test"

Links

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