sap-jenkins-library/resources/metadata/artifactPrepareVersion.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.          
        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
  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