Skip to content

artifactPrepareVersion

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

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 optionally 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 slightly 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 described 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.

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

library('piper-lib-os')

artifactPrepareVersion script: this
piper artifactPrepareVersion

Outputs

Output type Details
commonPipelineEnvironment
  • artifactVersion
  • originalArtifactVersion
  • artifactId
  • groupId
  • packaging
  • git/commitId
  • git/headCommitId
  • git/commitMessage

Parameters

Overview - Step

Name Mandatory Additional information
CAPVersioningPreference (yes) mandatory in case of:
- buildTool=CAP
buildTool yes
script (yes) Jenkins only reference to Jenkins main pipeline script
additionalTargetDescriptors no
additionalTargetTools no
commitUserName no
customTlsCertificateLinks no
customVersionField no
customVersionSection no
customVersioningScheme no
dockerVersionSource no
fetchCoordinates no
filePath no
globalSettingsFile no
includeCommitId no
isOptimizedAndScheduled no
m2Path no
password no Vault Secret pass via ENV, Vault or Jenkins credentials (gitHttpsCredentialsId)
projectSettingsFile no
shortCommitId no
tagPrefix no
unixTimestamp no
username no Vault Secret pass via ENV, Vault or Jenkins credentials (gitHttpsCredentialsId)
verbose no activates debug output
versioningTemplate no
versioningType no

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name Mandatory Additional information
containerCommand no Jenkins only
containerShell no Jenkins only
dockerEnvVars no
dockerImage no
dockerName no
dockerOptions no
dockerPullImage no
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only

Details

CAPVersioningPreference

If maven is chosen (default value), then the step expects a pom.xml file in the project's root folder. Alternatively, you can specify the path to the file using the filePath parameter. If npm is chosen, then the step expects a package.json file in the project's root folder. Alternatively, you can specify the path to the file using the filePath parameter.

In case you want to propagate version to addition file(s), it can be done via additionalTargetTools and additionalTargetDescriptors parameters.

back to overview

Scope Details
Aliases -
Type string
Mandatory mandatory in case of:
- buildTool=CAP
Default maven
Possible values - maven
- npm
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

additionalTargetDescriptors

Only for versioning types cloud and cloud_noTag. In case default build descriptors cannot be used for additionalTargetTools this parameter allows to define a dedicated search pattern per build tool. For each entry in additionalTargetTools a dedicated entry has to be maintained.

You can use either a file name or a glob pattern like **/package.json.

For helm the default value is **/Chart.yaml, thus typically no adaptions are required, but if a helm chart contains nested chart(s), the parameter needs to be set explicitly.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default $PIPER_additionalTargetDescriptors (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

additionalTargetTools

Only for versioning types cloud and cloud_noTag. This parameter allows you to propagate the version to other build-tool specific descriptors. If the parameter additionalTargetDescriptors is not defined the default build descriptors are used.

One example is to propagate the version into a helm chart. This can be achieved like

steps:
  artifactPrepareVersion:
    additionalTargetTools:
      - helm

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default $PIPER_additionalTargetTools (if set)
Possible values - custom
- docker
- dub
- golang
- gradle
- helm
- maven
- mta
- npm
- pip
- sbt
- yarn
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

buildTool

Defines the tool which is used for building the artifact.

back to overview

Scope Details
Aliases -
Type string
Mandatory yes
Default $PIPER_buildTool (if set)
Possible values - custom
- docker
- dub
- golang
- gradle
- helm
- maven
- mta
- npm
- pip
- sbt
- yarn
- CAP
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

commitUserName

Defines the user name which appears in version control for the versioning update (in case versioningType: cloud).

back to overview

Scope Details
Aliases gitUserName
Type string
Mandatory no
Default Project Piper
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

containerCommand

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

containerShell

Jenkins-specific: Used for proper environment setup.

Allows to specify the shell to be executed for container with containerName.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

List containing download links of custom TLS certificates. This is required to ensure trusted connections to registries with custom certificates.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default buildTool=maven: <nil>
buildTool=gradle: <nil>
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

customVersionField

For buildTool: custom: Defines the field which contains the version in the descriptor file.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_customVersionField (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

customVersionSection

For buildTool: custom: Defines the section for version retrieval in vase a .ini/.cfg file is used.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_customVersionSection (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

customVersioningScheme

For buildTool: custom: Defines the versioning scheme to be used.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default maven
Possible values - docker
- maven
- pep440
- semver2
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerEnvVars

Jenkins-specific: Used for proper environment setup.

Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].

back to overview

Scope Details
Aliases -
Type map[string]string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerImage

Jenkins-specific: Used for proper environment setup.

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.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default buildTool=maven: maven:3.6-jdk-8
buildTool=CAP: maven:3.6-jdk-8
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerName

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerOptions

Jenkins-specific: Used for proper environment setup.

Docker options to be set when starting the container.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerPullImage

Jenkins-specific: Used for proper environment setup.

Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default buildTool=maven: true
buildTool=CAP: true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerVersionSource

For buildTool: docker: Defines the source of the version. Can be FROM, any supported buildTool or an environment variable name.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_dockerVersionSource (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerVolumeBind

Jenkins-specific: Used for proper environment setup.

Volumes that should be mounted into the docker container.

back to overview

Scope Details
Aliases -
Type map[string]string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerWorkspace

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

fetchCoordinates

If set to true the step will retreive artifact coordinates and store them in the common pipeline environment.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

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).

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_filePath (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

globalSettingsFile

Maven only - Path to the mvn settings file that should be used as global settings file.

back to overview

Scope Details
Aliases maven/globalSettingsFile
Type string
Mandatory no
Default $PIPER_globalSettingsFile (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

includeCommitId

Defines if the automatically generated version (versioningType: cloud) should include the commit id hash.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

isOptimizedAndScheduled

Whether the pipeline runs in optimized mode and the current execution is a scheduled one

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references commonPipelineEnvironment:
  reference to: custom/isOptimizedAndScheduled

m2Path

Maven only - Path to the location of the local repository that should be used.

back to overview

Scope Details
Aliases maven/m2Path
Type string
Mandatory no
Default $PIPER_m2Path (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

password

Password/token for git authentication.

back to overview

Scope Details
Aliases access_token
Type string
Mandatory no
Default $PIPER_password (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: gitHttpsCredentialsId
  reference to: password

Vault resource:
  name: gitHttpsCredentialVaultSecretName
  default value: gitHttpsCredential

Vault paths:
  • $(vaultPath)/gitHttpsCredential
  • $(vaultBasePath)/$(vaultPipelineName)/gitHttpsCredential
  • $(vaultBasePath)/GROUP-SECRETS/gitHttpsCredential

projectSettingsFile

Maven only - Path to the mvn settings file that should be used as project settings file.

back to overview

Scope Details
Aliases maven/projectSettingsFile
Type string
Mandatory no
Default $PIPER_projectSettingsFile (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

script

Jenkins-specific: Used for proper environment setup.

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.

back to overview

Scope Details
Aliases -
Type Jenkins Script
Mandatory yes
Default
Secret no
Configuration scope
  • ☐ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references none

shortCommitId

Defines if a short version of the commitId should be used. GitHub format is used (first 7 characters).

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

tagPrefix

Defines the prefix which is used for the git tag which is written during the versioning run (only versioningType: cloud).

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default build_
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

unixTimestamp

Defines if the Unix timestamp number should be used as build number instead of the standard date format.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

username

User name for git authentication

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_username (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: gitHttpsCredentialsId
  reference to: username

Vault resource:
  name: gitHttpsCredentialVaultSecretName
  default value: gitHttpsCredential

Vault paths:
  • $(vaultPath)/gitHttpsCredential
  • $(vaultBasePath)/$(vaultPipelineName)/gitHttpsCredential
  • $(vaultBasePath)/GROUP-SECRETS/gitHttpsCredential

verbose

verbose output

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

versioningTemplate

DEPRECATED: Defines the template for the automatic version which will be created

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_versioningTemplate (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

versioningType

Defines the type of versioning:

  • cloud: fully automatic while also commiting a tag into the git repository containing the updated build descriptors
  • cloud_noTag: fully 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

Please note: Type cloud will automatically fall back to cloud_noTag in case a pull request is being built or in case the pipeline runs in optimized and scheduled mode (in this mode no build is being performed and thus no version tag is required to persist the build input)

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default cloud
Possible values - cloud
- cloud_noTag
- library
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

gitHttpsCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Username with password' credentials ID containing username/password for http access to your git repository.

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

gitSshKeyCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'SSH Username with private key' credentials ID ssh key for accessing your git repository. You can find details about how to generate an ssh key in the GitHub documentation.

back to overview

Scope Details
Aliases gitCredentialsId (deprecated)
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages