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