mirror of
https://github.com/SAP/jenkins-library.git
synced 2024-12-12 10:55:20 +02:00
375 lines
14 KiB
YAML
375 lines
14 KiB
YAML
metadata:
|
|
name: artifactPrepareVersion
|
|
aliases:
|
|
- name: artifactSetVersion
|
|
- name: setVersion
|
|
deprecated: true
|
|
description: Prepares and potentially updates the artifact's version before building the artifact.
|
|
longDescription: |-
|
|
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.
|
|
spec:
|
|
inputs:
|
|
secrets:
|
|
- name: gitHttpsCredentialsId
|
|
description: Jenkins 'Username with password' credentials ID containing username/password for http access to your git repository.
|
|
type: jenkins
|
|
- name: gitSshKeyCredentialsId
|
|
description: 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](https://docs.github.com/en/enterprise/2.15/user/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
|
|
type: jenkins
|
|
aliases:
|
|
- name: gitCredentialsId
|
|
deprecated: true
|
|
params:
|
|
- name: additionalTargetTools
|
|
type: "[]string"
|
|
description: Additional buildTool targets where descriptors need to be updated besides the main `buildTool`.
|
|
longDescription: |
|
|
**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`](#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
|
|
```
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
possibleValues:
|
|
- custom
|
|
- docker
|
|
- dub
|
|
- golang
|
|
- gradle
|
|
- helm
|
|
- maven
|
|
- mta
|
|
- npm
|
|
- pip
|
|
- sbt
|
|
- yarn
|
|
- name: additionalTargetDescriptors
|
|
type: "[]string"
|
|
description: Defines patterns for build descriptors which should be used for option [`additionalTargetTools`](additionaltargettools).
|
|
longDescription: |
|
|
**Only for versioning types `cloud` and `cloud_noTag`.** In case default build descriptors cannot be used for [`additionalTargetTools`](additionaltargettools) this parameter allows to define a dedicated search pattern per build tool.
|
|
For each entry in [`additionalTargetTools`](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.
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: buildTool
|
|
type: string
|
|
description: Defines the tool which is used for building the artifact.
|
|
mandatory: true
|
|
scope:
|
|
- GENERAL
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
possibleValues:
|
|
- custom
|
|
- docker
|
|
- dub
|
|
- golang
|
|
- gradle
|
|
- helm
|
|
- maven
|
|
- mta
|
|
- npm
|
|
- pip
|
|
- sbt
|
|
- yarn
|
|
- name: commitUserName
|
|
aliases:
|
|
- name: gitUserName
|
|
type: string
|
|
description: "Defines the user name which appears in version control for the versioning update (in case `versioningType: cloud`)."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
default: Project Piper
|
|
- name: customVersionField
|
|
type: string
|
|
description: "For `buildTool: custom`: Defines the field which contains the version in the descriptor file."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: customVersionSection
|
|
type: string
|
|
description: "For `buildTool: custom`: Defines the section for version retrieval in vase a *.ini/*.cfg file is used."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: customVersioningScheme
|
|
type: string
|
|
description: "For `buildTool: custom`: Defines the versioning scheme to be used."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
possibleValues:
|
|
- docker
|
|
- maven
|
|
- pep440
|
|
- semver2
|
|
default: maven
|
|
- name: dockerVersionSource
|
|
type: string
|
|
description: "For `buildTool: docker`: Defines the source of the version. Can be `FROM`, any supported _buildTool_ or an environment variable name."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: fetchCoordinates
|
|
type: bool
|
|
description: If set to `true` the step will retreive artifact coordinates and store them in the common pipeline environment.
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: filePath
|
|
type: string
|
|
description: "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`)."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: globalSettingsFile
|
|
aliases:
|
|
- name: maven/globalSettingsFile
|
|
type: string
|
|
description: Maven only - Path to the mvn settings file that should be used as global settings file.
|
|
scope:
|
|
- GENERAL
|
|
- STEPS
|
|
- STAGES
|
|
- PARAMETERS
|
|
- name: includeCommitId
|
|
type: bool
|
|
description: "Defines if the automatically generated version (`versioningType: cloud`) should include the commit id hash."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
default: true
|
|
- name: isOptimizedAndScheduled
|
|
type: bool
|
|
description: Whether the pipeline runs in optimized mode and the current execution is a scheduled one
|
|
resourceRef:
|
|
- name: commonPipelineEnvironment
|
|
param: custom/isOptimizedAndScheduled
|
|
scope:
|
|
- PARAMETERS
|
|
- name: m2Path
|
|
aliases:
|
|
- name: maven/m2Path
|
|
type: string
|
|
description: Maven only - Path to the location of the local repository that should be used.
|
|
scope:
|
|
- GENERAL
|
|
- STEPS
|
|
- STAGES
|
|
- PARAMETERS
|
|
- name: password
|
|
aliases:
|
|
- name: access_token
|
|
type: string
|
|
description: Password/token for git authentication.
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
secret: true
|
|
resourceRef:
|
|
- name: gitHttpsCredentialsId
|
|
type: secret
|
|
param: password
|
|
- type: vaultSecret
|
|
name: gitHttpsCredentialVaultSecretName
|
|
default: gitHttpsCredential
|
|
- name: projectSettingsFile
|
|
aliases:
|
|
- name: maven/projectSettingsFile
|
|
type: string
|
|
description: Maven only - Path to the mvn settings file that should be used as project settings file.
|
|
scope:
|
|
- GENERAL
|
|
- STEPS
|
|
- STAGES
|
|
- PARAMETERS
|
|
- name: shortCommitId
|
|
type: bool
|
|
description: Defines if a short version of the commitId should be used. GitHub format is used (first 7 characters).
|
|
scope:
|
|
- STEPS
|
|
- STAGES
|
|
- PARAMETERS
|
|
- name: tagPrefix
|
|
type: string
|
|
description: "Defines the prefix which is used for the git tag which is written during the versioning run (only `versioningType: cloud`)."
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
default: build_
|
|
- name: unixTimestamp
|
|
type: bool
|
|
description: Defines if the Unix timestamp number should be used as build number instead of the standard date format.
|
|
scope:
|
|
- STEPS
|
|
- STAGES
|
|
- PARAMETERS
|
|
- name: username
|
|
type: string
|
|
description: User name for git authentication
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
secret: true
|
|
resourceRef:
|
|
- name: gitHttpsCredentialsId
|
|
type: secret
|
|
param: username
|
|
- type: vaultSecret
|
|
name: gitHttpsCredentialVaultSecretName
|
|
default: gitHttpsCredential
|
|
- name: versioningTemplate
|
|
type: string
|
|
description: "DEPRECATED: Defines the template for the automatic version which will be created"
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
- name: versioningType
|
|
type: string
|
|
description: Defines the type of versioning
|
|
longDescription: |
|
|
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)
|
|
scope:
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
default: cloud
|
|
possibleValues:
|
|
- cloud
|
|
- cloud_noTag
|
|
- library
|
|
- name: customTlsCertificateLinks
|
|
type: "[]string"
|
|
description: List containing download links of custom TLS certificates. This is required to ensure trusted connections to registries with custom certificates.
|
|
scope:
|
|
- GENERAL
|
|
- PARAMETERS
|
|
- STAGES
|
|
- STEPS
|
|
conditions:
|
|
- conditionRef: strings-equal
|
|
params:
|
|
- name: buildTool
|
|
value: maven
|
|
- name: buildTool
|
|
value: gradle
|
|
outputs:
|
|
resources:
|
|
- name: commonPipelineEnvironment
|
|
type: piperEnvironment
|
|
params:
|
|
- name: artifactVersion
|
|
- name: originalArtifactVersion
|
|
- name: artifactId
|
|
- name: groupId
|
|
- name: packaging
|
|
- name: git/commitId
|
|
- name: git/headCommitId
|
|
- name: git/commitMessage
|
|
containers:
|
|
- image: maven:3.6-jdk-8
|
|
conditions:
|
|
- conditionRef: strings-equal
|
|
params:
|
|
- name: buildTool
|
|
value: maven
|