To use GitVersion with GitLab CI, either use the MSBuild
Task or put the GitVersion executable in your
runner's PATH.
Tag pipelines
GitVersion uses GitLab's CI_COMMIT_TAG predefined variable
to identify the selected tag. This variable contains the tag name, such as
1.2.3, rather than the full refs/tags/1.2.3 reference. When it is nonempty,
GitVersion treats the build as a tag pipeline rather than using
CI_COMMIT_REF_NAME as a branch name.
Rerunning a historical tag pipeline after the branch has advanced can leave HEAD
detached at a commit that is no longer the tip of any branch. If normalization
cannot attach HEAD to a local branch, it checks the selected local tag. When
that tag resolves to the checked-out commit, GitVersion keeps HEAD detached and
avoids a remote lookup that could be ambiguous because GitLab advertises
refs/pipelines/* and refs/environments/*/deployments/* at the same commit.
Existing branch selection takes precedence when a local branch identifies HEAD.
The selected tag must exist locally and resolve to HEAD for this behavior to
apply. A missing or empty CI_COMMIT_TAG, a missing local tag, or a tag pointing
to a different commit does not bypass normal ref discovery. An unrelated local
tag does not identify the build. This behavior does not replace the full Git
history required for version calculation.
Merge Request pipelines
In merge request pipelines GitLab sets CI_MERGE_REQUEST_REF_PATH (for example
refs/merge-requests/15/head or refs/merge-requests/15/merge). GitVersion
reads this variable through the GitLabCi build agent when it is present,
following the same pass-through pattern as Azure Pipelines (BUILD_SOURCEBRANCH)
and GitHub Actions (GITHUB_REF).
Branch resolution order in GitLabCi:
CI_COMMIT_TAGset โ treat as a tag pipeline (GetCurrentBranchreturnsnull)CI_MERGE_REQUEST_REF_PATHset โ use the merge request ref- otherwise โ
CI_COMMIT_REF_NAME(branch name)
After repository normalisation the friendly branch name becomes
merge-requests/<iid>/head or merge-requests/<iid>/merge. Extend the
pull-request branch configuration in GitVersion.yml so the regex matches
GitLab's namespace (the default pull-requests|pull|pr pattern does not):
workflow: GitFlow/v1
calculation:
branches:
pull-request:
label: PullRequest{Number}
regex: ^merge-requests/(?<Number>\d+)/(head|merge)$
CI_COMMIT_REF_NAME still contains the source branch name (for example
feature/foo) in MR pipelines; it is ignored when CI_MERGE_REQUEST_REF_PATH
is set.
A working example of integrating GitVersion with GitLab is maintained in the project Utterly Automated Versioning
Here is a summary of what it demonstrated (many more details in the Readme)
- Is a reusable working example known as a Guided Exploration (Guided Exploration Manifesto) - so job logs and package artifacts can be reviewed. The project can also be imported to your own GitLab group or instance as a starting point for your own work.
- IMPORTANT: It demonstrates how to override GitLab CI's default cloning behavior so that GitVersion can do a dynamic copy. Selectively clones GitVersion.yml so that these settings take effect. This best practice demonstrates the best way to do this while avoiding a double-cloning of the project (once by GitLab Runner and once by GitVersion).
- Implements GitVersion as a CI/CD Extension that can be reused across many projects using includes.
- Implements GitVersion as a single job that runs the GitVersion container and passes the version number downstream into both pipeline and job level variables, which means...
- It can be used with ANY coding language, framework or packaging engine.
- Generates example packaged artifacts:
- Two ways of building Sem Versioned NuGet packages (msbuild-ish and nuget.exe-ish) and uploads them and tests them from a GitLab NuGet Repository.
- A Sem Versioned GitLab Generic Package
- A Sem Versioned docker container and uploads to GitLab Container Registry.
- It creates a Sem Versioned GitLab Release and Git tag using the GitLab Release Cli and links the generic package as evidence.