github.com/jaylevin/jenkins-library@v1.230.4/resources/metadata/artifactPrepareVersion.yaml (about) 1 metadata: 2 name: artifactPrepareVersion 3 aliases: 4 - name: artifactSetVersion 5 - name: setVersion 6 deprecated: true 7 description: Prepares and potentially updates the artifact's version before building the artifact. 8 longDescription: |- 9 Prepares and potentially updates the artifact's version before building the artifact. 10 11 The continuous delivery process requires that each build is done with a unique version number. 12 There are two common patterns found: 13 14 ### 1. Continuous Deployment pattern with automatic versioning 15 16 The team has full authority on `<major>.<minor>.<patch>` and can increase any part whenever required. 17 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. 18 19 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>`). 20 21 Depending on the build tool used and thus the allowed versioning format the `<unique extension>` varies. 22 23 **Remarks:** 24 25 * 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 ... 26 * Not creating a tag would lead to a loss of the final artifact version in scm which often is not acceptable 27 * You need to ensure that your CI/CD system can push back to your SCM (via providing ssh or HTTP(s) credentials) 28 29 **This pattern is the default** behavior (`versioningType: cloud`) since this is suitable for most cloud deliveries. 30 31 It is possible to use `versioningType: cloud_noTag` which has a slightly different behavior than described above: 32 33 * The new version will NOT be written as tag into the SCM but it is only available in the corresponding CI/CD workspace 34 * 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. 35 36 ### 2. Pure version `<major>.<minor>.<patch>` 37 38 This pattern is often used by teams that have cloud deliveries with no fully automated procedure, e.g. delivery after each takt. 39 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. 40 41 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. 42 43 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. 44 45 Configuration of this pattern is done via `versioningType: library`. 46 47 ### Support of additional build tools 48 49 Besides the `buildTools` provided out of the box (like `maven`, `mta`, `npm`, ...) it is possible to set `buildTool: custom`. 50 51 This allows you to provide automatic versioning for tools using a: 52 53 #### file with the version as only content: 54 55 Define `buildTool: custom` as well as `filePath: <path to your file>` 56 57 **Please note:** `<path to your file>` need to point either to a `*.txt` file or to a file without extension. 58 59 #### `ini` file containing the version: 60 61 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. 62 63 **Please note:** `<path to your file>` need to point either to a `*.cfg` or a `*.ini` file. 64 65 #### `json` file containing the version: 66 67 Define `buildTool: custom`, `filePath: <path to your *.json file` as well as parameter `versionSource` to point to the parameter containing the version. 68 69 #### `yaml` file containing the version 70 71 Define `buildTool: custom`, `filePath: <path to your *.yml/*.yaml file` as well as parameter `versionSource` to point to the parameter containing the version. 72 spec: 73 inputs: 74 secrets: 75 - name: gitHttpsCredentialsId 76 description: Jenkins 'Username with password' credentials ID containing username/password for http access to your git repository. 77 type: jenkins 78 - name: gitSshKeyCredentialsId 79 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). 80 type: jenkins 81 aliases: 82 - name: gitCredentialsId 83 deprecated: true 84 params: 85 - name: additionalTargetTools 86 type: "[]string" 87 description: Additional buildTool targets where descriptors need to be updated besides the main `buildTool`. 88 longDescription: | 89 **Only for versioning types `cloud` and `cloud_noTag`.** This parameter allows you to propagate the version to other build-tool specific descriptors. 90 If the parameter [`additionalTargetDescriptors`](#additionaltargetdescriptors) is not defined the default build descriptors are used. 91 92 One example is to propagate the version into a helm chart. 93 This can be achieved like 94 95 ``` 96 steps: 97 artifactPrepareVersion: 98 additionalTargetTools: 99 - helm 100 ``` 101 scope: 102 - PARAMETERS 103 - STAGES 104 - STEPS 105 possibleValues: 106 - custom 107 - docker 108 - dub 109 - golang 110 - gradle 111 - helm 112 - maven 113 - mta 114 - npm 115 - pip 116 - sbt 117 - yarn 118 - name: additionalTargetDescriptors 119 type: "[]string" 120 description: Defines patterns for build descriptors which should be used for option [`additionalTargetTools`](additionaltargettools). 121 longDescription: | 122 **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. 123 For each entry in [`additionalTargetTools`](additionaltargettools) a dedicated entry has to be maintained. 124 125 You can use either a file name or a glob pattern like `**/package.json`. 126 127 For `helm` the default value is `**/Chart.yaml`, thus typically no adaptions are required. 128 scope: 129 - PARAMETERS 130 - STAGES 131 - STEPS 132 - name: buildTool 133 type: string 134 description: Defines the tool which is used for building the artifact. 135 mandatory: true 136 scope: 137 - GENERAL 138 - PARAMETERS 139 - STAGES 140 - STEPS 141 possibleValues: 142 - custom 143 - docker 144 - dub 145 - golang 146 - gradle 147 - helm 148 - maven 149 - mta 150 - npm 151 - pip 152 - sbt 153 - yarn 154 - name: commitUserName 155 aliases: 156 - name: gitUserName 157 type: string 158 description: "Defines the user name which appears in version control for the versioning update (in case `versioningType: cloud`)." 159 scope: 160 - PARAMETERS 161 - STAGES 162 - STEPS 163 default: Project Piper 164 - name: customVersionField 165 type: string 166 description: "For `buildTool: custom`: Defines the field which contains the version in the descriptor file." 167 scope: 168 - PARAMETERS 169 - STAGES 170 - STEPS 171 - name: customVersionSection 172 type: string 173 description: "For `buildTool: custom`: Defines the section for version retrieval in vase a *.ini/*.cfg file is used." 174 scope: 175 - PARAMETERS 176 - STAGES 177 - STEPS 178 - name: customVersioningScheme 179 type: string 180 description: "For `buildTool: custom`: Defines the versioning scheme to be used." 181 scope: 182 - PARAMETERS 183 - STAGES 184 - STEPS 185 possibleValues: 186 - docker 187 - maven 188 - pep440 189 - semver2 190 default: maven 191 - name: dockerVersionSource 192 type: string 193 description: "For `buildTool: docker`: Defines the source of the version. Can be `FROM`, any supported _buildTool_ or an environment variable name." 194 scope: 195 - PARAMETERS 196 - STAGES 197 - STEPS 198 - name: fetchCoordinates 199 type: bool 200 description: If set to `true` the step will retreive artifact coordinates and store them in the common pipeline environment. 201 scope: 202 - PARAMETERS 203 - STAGES 204 - STEPS 205 - name: filePath 206 type: string 207 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`)." 208 scope: 209 - PARAMETERS 210 - STAGES 211 - STEPS 212 - name: globalSettingsFile 213 aliases: 214 - name: maven/globalSettingsFile 215 type: string 216 description: Maven only - Path to the mvn settings file that should be used as global settings file. 217 scope: 218 - GENERAL 219 - STEPS 220 - STAGES 221 - PARAMETERS 222 - name: includeCommitId 223 type: bool 224 description: "Defines if the automatically generated version (`versioningType: cloud`) should include the commit id hash." 225 scope: 226 - PARAMETERS 227 - STAGES 228 - STEPS 229 default: true 230 - name: isOptimizedAndScheduled 231 type: bool 232 description: Whether the pipeline runs in optimized mode and the current execution is a scheduled one 233 resourceRef: 234 - name: commonPipelineEnvironment 235 param: custom/isOptimizedAndScheduled 236 scope: 237 - PARAMETERS 238 - name: m2Path 239 aliases: 240 - name: maven/m2Path 241 type: string 242 description: Maven only - Path to the location of the local repository that should be used. 243 scope: 244 - GENERAL 245 - STEPS 246 - STAGES 247 - PARAMETERS 248 - name: password 249 aliases: 250 - name: access_token 251 type: string 252 description: Password/token for git authentication. 253 scope: 254 - PARAMETERS 255 - STAGES 256 - STEPS 257 secret: true 258 resourceRef: 259 - name: gitHttpsCredentialsId 260 type: secret 261 param: password 262 - type: vaultSecret 263 name: gitHttpsCredentialVaultSecretName 264 default: gitHttpsCredential 265 - name: projectSettingsFile 266 aliases: 267 - name: maven/projectSettingsFile 268 type: string 269 description: Maven only - Path to the mvn settings file that should be used as project settings file. 270 scope: 271 - GENERAL 272 - STEPS 273 - STAGES 274 - PARAMETERS 275 - name: shortCommitId 276 type: bool 277 description: Defines if a short version of the commitId should be used. GitHub format is used (first 7 characters). 278 scope: 279 - STEPS 280 - STAGES 281 - PARAMETERS 282 - name: tagPrefix 283 type: string 284 description: "Defines the prefix which is used for the git tag which is written during the versioning run (only `versioningType: cloud`)." 285 scope: 286 - PARAMETERS 287 - STAGES 288 - STEPS 289 default: build_ 290 - name: unixTimestamp 291 type: bool 292 description: Defines if the Unix timestamp number should be used as build number instead of the standard date format. 293 scope: 294 - STEPS 295 - STAGES 296 - PARAMETERS 297 - name: username 298 type: string 299 description: User name for git authentication 300 scope: 301 - PARAMETERS 302 - STAGES 303 - STEPS 304 secret: true 305 resourceRef: 306 - name: gitHttpsCredentialsId 307 type: secret 308 param: username 309 - type: vaultSecret 310 name: gitHttpsCredentialVaultSecretName 311 default: gitHttpsCredential 312 - name: versioningTemplate 313 type: string 314 description: "DEPRECATED: Defines the template for the automatic version which will be created" 315 scope: 316 - PARAMETERS 317 - STAGES 318 - STEPS 319 - name: versioningType 320 type: string 321 description: Defines the type of versioning 322 longDescription: | 323 Defines the type of versioning: 324 325 * `cloud`: fully automatic while also commiting a tag into the git repository containing the updated build descriptors 326 * `cloud_noTag`: fully automatic but no tag created 327 * `library`: manual, i.e. the pipeline will pick up the version from the build descriptor, but not generate a new version 328 329 **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 330 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) 331 scope: 332 - PARAMETERS 333 - STAGES 334 - STEPS 335 default: cloud 336 possibleValues: 337 - cloud 338 - cloud_noTag 339 - library 340 outputs: 341 resources: 342 - name: commonPipelineEnvironment 343 type: piperEnvironment 344 params: 345 - name: artifactVersion 346 - name: originalArtifactVersion 347 - name: artifactId 348 - name: groupId 349 - name: packaging 350 - name: git/commitId 351 - name: git/headCommitId 352 - name: git/commitMessage 353 containers: 354 - image: maven:3.6-jdk-8 355 conditions: 356 - conditionRef: strings-equal 357 params: 358 - name: buildTool 359 value: maven