Skip to content

artifactPrepareVersion

Description

Prepares and potentially updates the artifact's version before building the artifact.

The continuous delivery process requires that each build is done with a unique version number. There are two common patterns found:

1. Continuous Deployment pattern with automatic versioning

The team has full authority on <major>.<minor>.<patch> and can increase any part whenever required. Nonetheless, the automatic versioning makes sure that every build will create a unique version by appending <major>.<minor>.<patch> with a buildversion (we use a timestamp) and optinally the commitId.

In order to represent this version also in the version control system the new unique version will be pushed with a dedicated tag (<tagPrefix><major>.<minor>.<patch><unique extension>).

Depending on the build tool used and thus the allowed versioning format the <unique extension> varies.

Remarks:

  • There is no commit to master since this would create a perpetuum mobile and just trigger the next automatic build with automatic versioning, and so on ...
  • Not creating a tag would lead to a loss of the final artifact version in scm which often is not acceptable
  • You need to ensure that your CI/CD system can push back to your SCM (via providing ssh or HTTP(s) credentials)

This pattern is the default behavior (versioningType: cloud) since this is suitable for most cloud deliveries.

It is possible to use versioningType: cloud_noTag which has a slighly different behavior than described above:

  • The new version will NOT be written as tag into the SCM but it is only available in the corresponding CI/CD workspace
  • IMPORTANT NOTICE: Using the option cloud_noTag should not be picked in case you need to ensure a fully traceable path from SCM commit to your build artifact.

2. Pure version <major>.<minor>.<patch>

This pattern is often used by teams that have cloud deliveries with no fully automated procedure, e.g. delivery after each takt. Another typical use-case is development of a library with regular releases where the versioning pattern should be consumable and thus ideally complies to a <major>.<minor>.<patch> pattern.

The version is then either manually set by the team in the course of the development process or automatically pushed to master after a successful release.

Unlike for the Continuous Deloyment pattern descibed above, in this case there is no dedicated tagging required for the build process since the version is already available in the repository.

Configuration of this pattern is done via versioningType: library.

Support of additional build tools

Besides the buildTools provided out of the box (like maven, mta, npm, ...) it is possible to set buildTool: custom.

This allows you to provide automatic versioning for tools using a:

file with the version as only content:

Define buildTool: custom as well as filePath: <path to your file>

Please note: <path to your file> need to point either to a *.txt file or to a file without extension.

ini file containing the version:

Define buildTool: custom, filePath: <path to your ini-file> as well as parameters versionSection and versionSource to point to the version location (section & parameter name) within the file.

Please note: <path to your file> need to point either to a *.cfg or a *.ini file.

json file containing the version:

Define buildTool: custom, filePath: <path to your *.json file as well as parameter versionSource to point to the parameter containing the version.

yaml file containing the version

Define buildTool: custom, filePath: <path to your *.yml/*.yaml file as well as parameter versionSource to point to the parameter containing the version.

Prerequisites

none

Example

Jenkins pipelines

artifactPrepareVersion script: this, buildTool: 'maven'

Command line

piper artifactPrepareVersion --buildTool maven

Parameters

name mandatory default possible values
buildTool Yes custom, docker, dub, golang, maven, mta, npm, pip, sbt
commitUserName No Project Piper
customVersionField No
customVersionSection No
customVersioningScheme No
dockerEnvVars No buildTool=maven: []
dockerImage No buildTool=maven: maven:3.6-jdk-8
dockerOptions No buildTool=maven: []
dockerPullImage No false
dockerVersionSource No
dockerWorkspace No buildTool=maven: \
filePath No
gitHttpsCredentialsId Yes
gitSshKeyCredentialsId Yes
globalSettingsFile No
includeCommitId No true true, false
m2Path No
password No
projectSettingsFile No
script Yes
shortCommitId No false true, false
tagPrefix No build_
unixTimestamp No false true, false
username No
verbose No false true, false
versioningTemplate No
versioningType No cloud cloud, cloud_noTag, library
  • buildTool: Defines the tool which is used for building the artifact. Supports custom, dub, golang, maven, mta, npm, pip, sbt.
  • commitUserName: Defines the user name which appears in version control for the versioning update (in case versioningType: cloud).
  • customVersionField: For buildTool: custom: Defines the field which contains the version in the descriptor file.
  • customVersionSection: For buildTool: custom: Defines the section for version retrieval in vase a .ini/.cfg file is used.
  • customVersioningScheme: For buildTool: custom: Defines the versioning scheme to be used (possible options pep440, maven, semver2).
  • dockerEnvVars: Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
  • dockerImage: Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.
  • dockerOptions: Docker options to be set when starting the container.
  • dockerPullImage: Set this to 'false' to bypass a docker image pull. Usefull during development process. Allows testing of images which are available in the local registry only.
  • dockerVersionSource: For buildTool: docker: Defines the source of the version. Can be FROM, any supported buildTool or an environment variable name.
  • dockerWorkspace: Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.
  • filePath: Defines a custom path to the descriptor file. Build tool specific defaults are used (e.g. maven: pom.xml, npm: package.json, mta: mta.yaml).
  • globalSettingsFile: Maven only - Path to the mvn settings file that should be used as global settings file.
  • includeCommitId: Defines if the automatically generated version (versioningType: cloud) should include the commit id hash.
  • m2Path: Maven only - Path to the location of the local repository that should be used.
  • password: Password/token for git authentication.
  • projectSettingsFile: Maven only - Path to the mvn settings file that should be used as project settings file.
  • script: The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.
  • shortCommitId: Defines if a short version of the commitId should be used. GitHub format is used (first 7 characters).
  • tagPrefix: Defines the prefix which is used for the git tag which is written during the versioning run (only versioningType: cloud).
  • unixTimestamp: Defines if the Unix timestamp number should be used as build number instead of the standard date format.
  • username: User name for git authentication
  • verbose: verbose output
  • versioningTemplate: DEPRECATED: Defines the template for the automatic version which will be created
  • versioningType: Defines the type of versioning (cloud: fully automatic, cloud_noTag: automatic but no tag created, library: manual, i.e. the pipeline will pick up the version from the build descriptor, but not generate a new version)

Step Configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter general step/stage
buildTool X X
commitUserName X
customVersionField X
customVersionSection X
customVersioningScheme X
dockerEnvVars X
dockerImage X
dockerOptions X
dockerPullImage X
dockerVersionSource X
dockerWorkspace X
filePath X
globalSettingsFile X X
includeCommitId X
m2Path X X
password X
projectSettingsFile X X
shortCommitId X
tagPrefix X
unixTimestamp X
username X
verbose X
versioningTemplate X
versioningType X