# GitLab Branch<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; | &#10007;
|===

== 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 link:https://github.com/updatecli/updatecli/issues[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:

[source,text]
----
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 link:/docs/plugins/resource/gitBranch/[`gitbranch`].

== Parameters

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

`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 link:/docs/core/versionfilter/["Version Filtering" page].

== 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
----

Reading a public repository works without any credential.

== Example

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

== Links

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