GitHub Actions

Installation and usage

For GitHub Actions you can install the action from GitTools Bundle.

Important

You must disable shallow fetch by setting fetch-depth: 0 in your checkout step; without it, GitHub Actions might perform a shallow clone, which will cause GitVersion to display an error message.

More information can be found at gittools/actions.

Branch and tag builds

GitVersion uses the following GitHub Actions default environment variables to identify the ref being built:

Variable How GitVersion uses it
GITHUB_REF_TYPE Distinguishes tag builds (tag) from branch builds (branch).
GITHUB_REF Supplies the full ref, such as refs/heads/main, refs/pull/42/merge, or refs/tags/1.2.3.

For a tag build, GitVersion treats GITHUB_REF as the selected tag rather than a branch name. This also applies when manually running a workflow with workflow_dispatch and selecting a tag.

A historical tag can point to 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 an unnecessary remote lookup for pull-request refs. 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. Checking out a different ref from the one reported by GITHUB_REF does not make an unrelated local tag identify the build. Keep fetch-depth: 0 as described above so GitVersion has the full history available for version calculation.