Skip to content
git-merge

GitHub Action

Nerdbank.GitVersioning

v0.4.2 Latest version

Nerdbank.GitVersioning

git-merge

Nerdbank.GitVersioning

Creates deterministic versions using git

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Nerdbank.GitVersioning

              
  uses: dotnet/nbgv@v0.4.2
Learn more about this action in dotnet/nbgv

Choose a version

GitHub Action for Nerdbank.GitVersioning

GitHub Actions status

This action installs the CLI for Nerdbank.GitVersioning and exposes version data from it as action outputs. It optionally also sets environment variables.

⌚ The action runs in about 5 seconds.

This project is supported by the .NET Foundation.

Inputs

All inputs are optional.

Name Default Description
path Repo root The path to the directory for which the version should be determined. This should be at or below the directory containing the version.json file.
setCommonVars false Defines a few common version variables as environment variables, with a "Git" prefix (e.g. GitBuildVersion, GitBuildVersionSimple, GitAssemblyInformationalVersion). Adds the --common-vars switch to the nbgv cloud command.
setAllVars false Defines ALL version variables as environment variables, with a "NBGV_" prefix. Adds the --all-vars switch to the nbgv cloud command.
stamp The path to a file whose version setting should be changed to match the computed version. Supported file types: package.json
toolVersion latest stable The version of the nbgv dotnet CLI tool to install and use. If not specified, the default is the latest stable version.
toolFeed nuget.config content An additional feed to search for the nbgv dotnet CLI tool. Default feeds may include https://api.nuget.org/v3/index.json or whatever is specified in a nuget.config file at the root of your repo.

Outputs

Name Description
CloudBuildNumber The cloud build number
VersionFileFound A boolean value indicating whether a version.json file was found.
AssemblyVersion The version to be used as the .NET assembly version.
AssemblyFileVersion The version to be used as the .NET assembly file version.
AssemblyInformationalVersion The version to be used as the .NET assembly informational version.
PublicRelease A boolean value indicating whether this build is recognized as building from a public release branch.
PrereleaseVersion The prerelease/unstable suffix to the version, including the hyphen.
PrereleaseVersionNoLeadingHyphen The prerelease/unstable suffix to the version, without the leading hyphen.
SimpleVersion The first 3 integers of the version.
BuildNumber The build number (i.e. the third integer or PATCH) for this version.
VersionRevision The fourth integer component of the version.
MajorMinorVersion The "major.minor" portion of the version.
VersionMajor The first integer of the version.
VersionMinor The second integer of the version.
GitCommitId The full SHA1 hash of the HEAD commit.
GitCommitIdShort A truncated SHA1 hash of the HEAD commit (usually 10 characters)
GitCommitDate The date of the git commit at HEAD
VersionHeight The number of commits in the longest single path between the specified commit and the most distant ancestor (inclusive) that set the version to the value at HEAD.
VersionHeightOffset The offset to add to VersionHeight when calculating the BuildNumber or wherever else the VersionHeight is used.
Version The four integer version.
BuildMetadataFragment The +metadata portion of the version, if any.
NuGetPackageVersion The version to be used for NuGet packages.
ChocolateyPackageVersion The version to be used for Chocolatey packages.
NpmPackageVersion The version to be used for NPM packages.
SemVer1 The SemVer 1.0 compliant version.
SemVer2 The SemVer 2.0 compliant version.

Example usage

In each example below, replace the master branch reference in @master with the latest versioned branch available at the time you consume it. This will help your consumption be stable even as we (may) make breaking changes. You can always unlock new features in the Action by bumping the v0.x to v0.x+1 later.

Using step outputs

- uses: dotnet/nbgv@master
  id: nbgv
- run: echo 'SemVer2=${{ steps.nbgv.outputs.SemVer2 }}'

Using environment variables

- uses: dotnet/nbgv@master
  with:
    setAllVars: true
- run: echo "NBGV_SemVer2 $NBGV_SemVer2"

Stamp the version on a package.json file

- uses: dotnet/nbgv@master
  with:
    stamp: package.json

Checkout requirements

Git history based versioning tools rely on history being included in the clone. actions/checkout@v1 does this by default. But if you're using actions/checkout@v2 you'll need to specify deep clone:

- uses: actions/checkout@v2
  with:
    fetch-depth: 0 # avoid shallow clone so nbgv can do its work.

Contribution guidelines

Prerequisites and build instructions are found in our contributing guidelines.