Settings

Configuration settings for the sbt plugin.

Available Keys

versionRead

Customise how Git tags are parsed into Version values. The plugin uses the standard SemVer parser by default.

versionRead := Version.Read.ReadString

For custom parsers, see Parsing — Custom Read.

versionResolver

Customise how pre-release identifiers from Git tags are mapped to version.PreRelease values. The default resolver recognises standard classifiers (alpha, beta, rc, etc.) and their aliases.

versionResolver := PreRelease.Resolver.given_Resolver

For custom resolvers, see Parsing — Custom Resolver.

versionShow

Controls how ThisBuild / version is rendered. None means "use version.Version.Show.Standard," which excludes build metadata. Supply Some(showInstance) to override the behaviour.

versionShow := Some(Version.Show.Extended) // include metadata
versionShow := None                        // default (no metadata)

For custom Show implementations, see Operations — Rendering.

resolvedVersion

The fully resolved version.Version value for the current repository state. The plugin always records the complete 40-character commit SHA in build metadata; rendering logic decides how much to surface.

val v = resolvedVersion.value
val core = s"${v.major.value}.${v.minor.value}.${v.patch.value}"

Use this when you need structured data (e.g. to derive Docker tags) rather than the pre-rendered string.

versionBranchOverride

Override the branch name detected from Git. Useful when CI performs detached checkouts.

versionBranchOverride := sys.env.get("GITHUB_REF_NAME")

When unset, the plugin falls back to Git's current branch (if available).

Environment Hooks

Two environment variables influence resolution:

• VERSION_BRANCH — overrides the detected branch name (same effect as versionBranchOverride)
• VERSION_VERBOSE — enables verbose logging from the underlying CLI core when set to a truthy value

Example Configuration

// build.sbt
versionBranchOverride := sys.env.get("GITHUB_REF_NAME")
versionRead := Version.Read.ReadString
versionShow := Some(Version.Show.Extended)

// Access the structured version when needed
def dockerTag = resolvedVersion.value.show(using Version.Show.Extended)