13 minute read

Top level attributes

The following attributes are at the top of the hierarchy:

Name Type Values
branch string The current Git branch
bump string The bumped version identifier
changelog object The changelog data model
configuration object The resolved configuration
coreVersion boolean true if version is core
directory string Directory path
internals map Name-Value pairs
latestVersion boolean true if version is the latest
newRelease boolean true if a new release has to be issued
newVersion boolean true if a new version has been generated
releaseScope object The release scope attributes
releaseType string The selected release type
scheme string SEMVER
timestamp integer A positive integer
version string The current version
versionBuildMetadata string The version build metadata
versionMajorNumber string The version major number
versionMinorNumber string The version minor number
versionPatchNumber string The version patch number
versionPreReleaseIdentifier string The version pre-release identifier
versionRange string The version range regular expression

Branch

Name branch
Type string
Related configuration options  
Initialized by task infer

This string contains the current Git branch name.

This attribute is not initialized if the version configuration option was passed to override inference.

This attribute is not available until infer has run.

Bump

Name bump
Type string
Related configuration options bump initialVersion releaseTypes/ID/collapseVersions scheme version
Initialized by task infer

This string contains the name of the identifier that has been bumped to create the new version. Version identifiers depend on the selected version scheme.

This attribute is not initialized if the version configuration option was passed to override inference or the release scope does not contain significant changes to be released.

This attribute is not available until infer has run.

When using collapsed versioning this attribute contains the value of the bumped core identifier only (if any was bumped), not the collapsed version qualifier. Broadly speaking, no extra identifier is ever used to set this value. This might be misleading as sometimes you don’t see the core identifier actually bumped on the previous version as it might have already been bumped on the prime version.

Changelog

Name changelog
Type object
Related configuration options See the details
Initialized by task make

This object holds the data used to render the changelog, documented here.

Please note that the changelog object is only present when the changelog generation has been enabled by setting the changelog path option.

Configuration

Name configuration
Type object
Related configuration options The entire configuration
Initialized by task any

This object holds a copy of the entire configuration resolved according to the evaluation order.

Core version

Name coreVersion
Type boolean
Related configuration options scheme version
Initialized by task infer

This value is true when the version only uses core identifiers (i.e. is not a pre-release) according to the scheme.

This attribute is not available until infer has run.

Directory

Name directory
Type string
Related configuration options directory
Initialized by task any

The path of current working directory.

Internals

Name internals
Type map
Related configuration options N/A
Initialized by task any

A map of attributes for internal use only.

Using the attributes in this section is not supported. You should never rely on the attributes in this block as they may change at any time without any notice.

Latest version

Name latestVersion
Type boolean
Related configuration options scheme version
Initialized by task infer

This value is true when the version is the latest in the repository, meaning that, according to the scheme, there are no other tags in the Git repository representing any version greater than version.

Remember that when inspecting all the tags in te current repository Nyx needs to have access to all of them. It’s a common practice for CI/CD platform to only check out the latest commit or, in general, reduce the size of the local repository by not fetching all informations. If that’s the case, this attribute may give incorrect results just because Nyx just can’t see all the tags in the repository. See here for more on how to make sure the whole repository is available when cloned.

This attribute is not available until infer has run.

New release

Name newRelease
Type boolean
Related configuration options bump initialVersion releasePrefix releaseTypes/ID/publish scheme version
Initialized by task infer

This value is true when the newVersion is true and a new release with the current version has to be issued.

This is basically a shorthand to testing if version is different than the releaseScope/previousVersion and publishing is enabled for the current release type.

This attribute is not available until infer has run.

New version

Name newVersion
Type boolean
Related configuration options bump initialVersion releasePrefix scheme version
Initialized by task infer

This value is true when the version is new and is basically a shorthand to testing if version is different than the releaseScope/previousVersion.

This attribute is not available until infer has run.

Release scope

Name releaseScope
Type object
Related configuration options  
Initialized by task infer

This object collects several attributes defining the release scope, documented here.

Release type

Name releaseType
Type object
Related configuration options releaseType
Initialized by task infer

This object references the release type that has been selected among the enabled ones by infer.

The referenced object has all the attributes modelled as configuration options of a releaseType and all templates are evaluated.

Scheme

Name scheme
Type string
Related configuration options bump initialVersion releaseLenient releasePrefix scheme version
Initialized by task any

The configured version scheme.

Timestamp

Name timestamp
Type integer
Related configuration options  
Initialized by task any

The timestamp in the Unix format (seconds since Jan 01 1970. (UTC). Example: 1591802533. See here for examples.

In order to grant consistency, whenever a timestamp is needed within the build process, this value should be used instead of reading it from the underlying system. This is to ensure that all timestamps coming from the same release are homogeneous.

Nyx sets this value once at the beginning of every execution.

If this is not used as the sole timestamp you may see a skew due to when the system timestamp is taken. Suppose that a task that needs the timestamp reads it 2 seconds after another: you have two different timestamps there, and you may have artifacts belonging to the same release not matching this field. Instead, using this sole source for time and date ensures the same value within the same release process. For sure this may not split the millisecond overall, but when you release you need consistency over this kind of precision.

Version

Name version
Type string
Related configuration options bump initialVersion releasePrefix scheme version
Initialized by task infer

The version that was inferred, unless the version configuration option was passed to override inference. When the version is not overridden or inferred the initialVersion is used.

Please note that this version might be the same as the releaseScope/previousVersion found in the Git commit history (or the initialVersion if the commit history does not contain any previous version) if the release scope has no significant changes. To know whether this is a new version or not you should check newVersion.

This attribute is not available until infer has run.

Version build metadata

Name versionBuildMetadata
Type string
Related configuration options version
Initialized by task infer

The version build metadata, if present in the version. This attribute is only available when the configured version scheme is SEMVER.

This attribute is not available until infer has run.

Version major number

Name versionMajorNumber
Type string
Related configuration options version
Initialized by task infer

The version major number. This attribute is only available when the configured version scheme is SEMVER.

This attribute is not available until infer has run.

Version minor number

Name versionMinorNumber
Type string
Related configuration options version
Initialized by task infer

The version minor number. This attribute is only available when the configured version scheme is SEMVER.

This attribute is not available until infer has run.

Version patch number

Name versionPatchNumber
Type string
Related configuration options version
Initialized by task infer

The version patch number. This attribute is only available when the configured version scheme is SEMVER.

This attribute is not available until infer has run.

Version pre-release identifier

Name versionPreReleaseIdentifier
Type string
Related configuration options version
Initialized by task infer

The version pre-release identifier, if present in the version. This attribute is only available when the configured version scheme is SEMVER.

This attribute is not available until infer has run.

Version range

Name versionRange
Type string
Related configuration options versionRange versionRangeFromBranchName
Initialized by task infer

The regular expression matched against the version to make sure it’s within a specific range.

This constraint is optional and depends on the versionRange and versionRangeFromBranchName configuration options. When the check is not enabled by this option this reference attribute remains undefined, otherwise it’s populated with a regular expression that is dynamically generated to match the current version. To be more specific, when versionRange is configured this value has the same value configured in versionRange after the template has been evaluated, otherwise if versionRangeFromBranchName is enabled this value has the dynamically generated regular expression as it’s inferred by the branch name.

This attribute is not available until infer has run.