GitHub - BredaUniversityGames/JenkinsLib GitHub Wiki

github.version() / github.release()

Computes the next semantic version from git tags and creates a GitHub Release with a generated changelog and uploaded assets.

The module is split into two stages that work together:

Stage Category Purpose
github.version() vcs Compute next version, set ctx.version and env.BUILD_VERSION
github.release() deploy Generate changelog, create release, upload assets

Usage

stages {
    git.sync()
    github.version()
    cmake.build(CMAKE_ARGS: '-DBUILD_VERSION=%BUILD_VERSION%')
    github.release()
    discord.alert()
}

With a matrix for multiple build presets:

stages {
    git.sync()
    github.version()
    matrix(CMAKE_BUILD_PRESET: ['Developer-Packaging', 'Release-Game']) {
        cmake.build(
            CMAKE_ARGS: '-DCMAKE_UNITY_BUILD=ON -DBUILD_VERSION=%BUILD_VERSION%',
            CMAKE_BUILD_ARGS: '--target game -j'
        )
    }
    github.release(GH_RELEASE_ASSETS: '*.zip')
    discord.alert()
}

Prerequisites

  • GitHub CLI (gh) installed on the Jenkins agent
  • A GitHub token stored as a Jenkins credential (see Credential Setup)
  • git.sync() must run before github.version() (the repository needs to be checked out)

Parameters

github.version()

Parameter Default Description
GH_CREDENTIALS_ID (empty) Jenkins credential for GitHub (Username with password — can reuse GIT_CREDENTIALS_ID)
GH_VERSION_BUMP patch Semver component to increment (patch, minor, or major)

github.release()

Parameter Default Description
GH_RELEASE_ASSETS *.zip Glob pattern for files to attach to the release
GH_RELEASE_NAME Release ${VERSION} Release title (${VERSION} is replaced with the computed version)
GH_RELEASE_DRAFT false Create as a draft release
GH_RELEASE_PRERELEASE false Mark as a pre-release

Credential Setup

The gh CLI authenticates via the GH_TOKEN environment variable. The pipeline extracts the token from the password field of a Username with password credential — the same type used by git.sync().

Reusing the git.sync() credential

If you already have a GIT_CREDENTIALS_ID credential configured for git.sync(), you can reuse it. Set GH_CREDENTIALS_ID to the same credential ID. The token must have Contents: Read and write permission (required to create releases and tags).

Creating a new credential

If you need a separate credential (e.g., with different permissions), follow the PAT setup instructions in git.sync() with these permissions:

  • Contents: Read and write (required to create releases and tags)
  • Metadata: Read-only (selected by default)

Use the credential ID as the GH_CREDENTIALS_ID parameter.

How It Works

Version Computation

  1. Runs git describe --tags --abbrev=0 to find the latest tag
  2. Parses the tag as a semver version (e.g., v1.2.3)
  3. Increments the selected component (patch by default: v1.2.3 -> v1.2.4)
  4. Stores the new version in ctx.version and env.BUILD_VERSION

If no tags exist, the version starts at v0.1.0.

Release Creation

  1. Generates a changelog from git log between the latest tag and HEAD
  2. Filters commits to Conventional Commits prefixes: feat:, fix:, breaking:, docs:, chore:, refactor:, perf:, test:, ci:, build:, style:
  3. Creates a GitHub Release via gh release create with the computed tag, title, and changelog
  4. Uploads all files matching the GH_RELEASE_ASSETS glob pattern

Using the Version in Build Steps

github.version() sets the BUILD_VERSION environment variable, which downstream build steps can reference:

CMake:

cmake.build(CMAKE_ARGS: '-DBUILD_VERSION=%BUILD_VERSION%')

MSBuild / Visual Studio:

vs.build(VS_BUILD_ARGS: '/p:Version=%BUILD_VERSION%')

Arbitrary build scripts:

bat "my-build-script.bat --version %BUILD_VERSION%"

Troubleshooting

Issue Solution
gh: command not found Install the GitHub CLI on the Jenkins agent and ensure it's on the system PATH
gh: authentication required Verify the GH_CREDENTIALS_ID credential contains a valid token with contents:write permission
ctx.version is not set Ensure github.version() is listed before github.release() in your pipeline
Version starts at v0.1.0 No git tags found — create an initial tag (git tag v0.0.0 && git push --tags) to set the baseline
Changelog is empty Commits must use Conventional Commits format (e.g., feat: add player movement) to appear in the changelog
⚠️ **GitHub.com Fallback** ⚠️