Git Branch

kind: gitbranch

source	condition	target
✔	✔	✔

source

The Git Branch "source" retrieves the latest git branch matching a pattern.

condition

The Git branch "condition" tests if git branch matching a pattern exist.

target

The Git branch "target" ensures a git branch matching a pattern exist otherwise it creates it.

Parameter

The git branch resource is a resource designed to be used with the scmID

Name	Type	Description
branch	string	branch specifies the branch name compatible: source condition target
depth	integer	Depth is used to limit the number of commits fetched from the git repository. compatible: source condition target default: 0 (no limit) remark: Updatecli won’t be able to find branches that are not included in the fetched commits.
key	string	“key” of the tag object to retrieve. Accepted values: [’name’,‘hash’]. Default: ’name’ Compatible: source
password	string	“password” specifies the password when using the HTTP protocol `compatible: * source * condition * target`
path	string	path contains the git repository path
sourcebranch	string	“url” specifies the git url to use for fetching Git Tags. `compatible: * source * condition * target example: * git@github.com:updatecli/updatecli.git * https://github.com/updatecli/updatecli.git remarks: when using the ssh protocol, the user must have the right to clone the repository based on its local ssh configuration`
url	string	“sourcebranch” defines the branch name used as a source to create the new Git branch. compatible: target remark: sourcebranch is required when the scmid is not defined.
username	string	“username” specifies the username when using the HTTP protocol `compatible * source * condition * target`
versionfilter	object	VersionFilter provides parameters to specify version pattern and its type like regex, semver, or just latest. compatible: source condition target
kind	string	specifies the version kind such as semver, regex, or latest
pattern	string	specifies 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
regex	string	specifies the regex pattern, used for regex/semver and regex/time. Output of the first capture group will be used.
replaceall	object	replaceAll 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.
strict	boolean	strict enforce strict versioning rule. Only used for semantic versioning at this time

Version Filter

versionFilter allows to specify the kind of version retrieved from a resource and its version pattern. Default value is "latest" as we want to retrieve the newest version from a resource.

latest

If kind is set to latest then no need to specify the patter as we gonna retrieve the newest version from the resource.

Example

sources:
 kubectl:
 kind: githubRelease
 spec:
 owner: "kubernetes"
 repository: "kubectl"
 token: "{{ requiredEnv .github.token }}"
 username: "john"
 versionFilter:
 kind: latest
 transformers:
 - trimPrefix: "kubernetes-"

Return the latest Github release and remove "kubernetes-" from it.

Lex

If the kind is set to lex then Updatecli returns the latest version sorted lexicographically.

Sorting versions lexicographically means arranging them based on their lexicographic order, which is essentially alphabetical order as used in dictionaries, but applied to version strings.

For example, in lexicographic order:

"1.10" comes before "1.2", because it compares character by character:
 Compare "1" vs. "1" → equal.
 Compare "." vs "." → equal.
 Compare "1" vs. "2" → "1" is smaller, so "1.10" < "1.2".

This ordering does not account for numerical values of version components. For meaningful version comparisons, semantic versioning is typically preferred, where "1.2" < "1.10" because "2" is numerically smaller than "10".

Example

sources:
 ubuntu-focal:
 name: Get latest ubuntu focal docker image tag using regex/time versionfilter
 kind: dockerimage
 spec:
 image: ubuntu
 versionfilter:
 kind: lex

regex

If versionFilter.kind is set to regex then we can use versionFilter.pattern to specify a regular expression to return the newest version returned from a resource matching the regex If no versionFilter.pattern is provided then it uses '.*' which return the newest version

versionFilter.replaceall can optionally be used to transform version strings before the regex is applied. It accepts a pattern (regex) and a replacement string, similar to a find-and-replace operation.

sources:
 kubectl:
 kind: githubRelease
 spec:
 owner: "kubernetes"
 repository: "kubectl"
 token: "{{ requiredEnv .github.token }}"
 username: "john"
 versionFilter:
 kind: regex
 pattern: "kubernetes-1.(\\d*).(\\d*)$"
 transformers:
 - trimPrefix: "kubernetes-"

⇒ Return the newest kubectl version matching pattern "kubernetes-1.(\\d*).(\\d*)$" and remove "kubernetes-" from it

Example with replaceall

Some projects use version tags that are not directly compatible with the regex pattern. For example, curl uses tags like curl-8_11_1 where underscores separate version components. The replaceall option can be used to normalize these tags before applying the regex.

sources:
 curl:
 kind: githubRelease
 spec:
 owner: "curl"
 repository: "curl"
 versionFilter:
 kind: regex
 regex: 'curl-(\d+\.\d+\.\d+)'
 replaceall:
 pattern: "_"
 replacement: "."

⇒ The replaceall converts curl-8_11_1 to curl-8.11.1 before matching, then the regex extracts 8.11.1

semver

If versionFilter.kind is set to semver then we can use versionFilter.pattern to specify version pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it fallback to '*' which return the newest version. If a version doesn’t respect semantic versioning, then it’s not the value is just ignored.

Remark

In the process we drop any characters not respecting semantic version like in this version "v1.0.0", we drop the "v" but we can added it back using transformers.

Example

 jenkins-wiki-exporter:
 kind: githubRelease
 spec:
 owner: "jenkins-infra"
 repository: "jenkins-wiki-exporter"
 token: "{{ requiredEnv .github.token }}"
 username: "john"
 versionFilter:
 kind: semver
 pattern: "~1.10"

⇒ Return the version "v1.10.3"

regex/semver

If versionFilter.kind is set to regex/semver then we can use versionFilter.regex to specify a regular expression to extract version numbers. The regular expression should return the semantic version in the first capturing group. We can then use versionFilter.pattern to specify version pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it fallback to '*' which return the newest version. If a extracted version doesn’t respect semantic versioning, then it’s not the value is just ignored.

Example

sources:
 default:
 name: Get latest version
 kind: githubrelease
 spec:
 owner: yarnpkg
 repository: berry
 token: '{{ requiredEnv "GITHUB_TOKEN" }}'
 versionfilter:
 kind: regex/semver
 regex: "@yarnpkg/cli/(\\d*\\.\\d*\\.\\d*)"

⇒ Return the version "4.5.3"

regex/time

If versionFilter.kind is set to regex/time then we can use versionFilter.regex to specify a regular expression to extract dates. The regular expression should return the date in the first capturing group. We can then use versionFilter.pattern to specify date pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it fallback to '2006-01-02' which return the newest version using date format YYYY-MM-DD. If a extracted date doesn’t match the date pattern, then it’s not the value is just ignored.

To define your own format/pattern, write down what the reference time would look like formatted your way; The model is to demonstrate what the reference time looks like so that the Format and Parse methods can apply the same transformation to a general time value.

Here is a summary of the components of a layout string. Each element shows by example the formatting of an element of the reference time. Only these values are recognized. Text in the layout string that is not recognized as part of the reference time is echoed verbatim during Format and expected to appear verbatim in the input to Parse.

Year: "2006" "06"
Month: "Jan" "January" "01" "1"
Day of the week: "Mon" "Monday"
Day of the month: "2" "_2" "02"
Day of the year: "__2" "002"
Hour: "15" "3" "03" (PM or AM)
Minute: "4" "04"
Second: "5" "05"
AM/PM mark: "PM"

You can get inspiration from the following examples

Pattern

Example

2006年01月02日

2021年01月02日 (YYYY-MM-DD)

20060102

20210102 (YYYYMMDD)

20060201

20260201 (YYYYDDMM)

Example

sources:
 ubuntu-focal:
 name: Get latest ubuntu focal docker image tag using regex/time versionfilter
 kind: dockerimage
 spec:
 image: ubuntu
 versionfilter:
 kind: 'regex/time'
 regex: '^focal-(\d*)$'
 pattern: "20060102"

time

If versionFilter.kind is set to time then we can use versionFilter.pattern to specify date pattern as explained here. In the process we also sort. If no versionFilter.pattern is provided then it fallback to '2006-01-02' which return the newest version using date format YYYY-MM-DD. Please note date time not matching the pattern will be ignored.

Year: "2006" "06"
Month: "Jan" "January" "01" "1"
Day of the week: "Mon" "Monday"
Day of the month: "2" "_2" "02"
Day of the year: "__2" "002"
Hour: "15" "3" "03" (PM or AM)
Minute: "4" "04"
Second: "5" "05"
AM/PM mark: "PM"

You can get inspiration from the following examples

Pattern

Example

2006年01月02日

2021年01月02日 (YYYY-MM-DD)

20060102

20210102 (YYYYMMDD)

20060201

20260201 (YYYYDDMM)

Example

sources:
 ubuntu:
 name: Get latest ubuntu docker image tag using time versionfilter
 kind: dockerimage
 spec:
 image: ubuntu
 versionfilter:
 kind: 'time'
 pattern: "06.01"

Example

# updatecli.yaml
scms:
 default:
 kind: github
 spec:
 branch: master
 email: me@olblak.com
 owner: updatecli-test
 repository: nocode
 token: '{{ requiredEnv "GITHUB_TOKEN" }}'
 user: updatecli
 username: '{{ requiredEnv "GITHUB_ACTOR" }}'
 disabled: false
sources:
 default:
 name: Get Latest branch using semantic versioning
 kind: gitbranch
 scmid: default
 spec:
 versionfilter:
 kind: semver
conditions:
 default:
 name: Test that branch returned from source exists
 kind: gitbranch
 scmid: default
 sourceid: default
 master:
 name: Test that branch master exists
 kind: gitbranch
 scmid: default
 disablesourceinput: true
 spec:
 branch: master
targets:
 default:
 name: Ensure the branch return from source if it doesn't exist
 kind: gitbranch
 scmid: default
 disablesourceinput: true
 spec:
 branch: v1
 alreadyexist:
 name: Ensure the branch "master" exists
 kind: gitbranch
 scmid: default
 spec:
 branch: master

Last modified on December 24, 2024

Edit this page on GitHub

← Terraform File

cargopackage →