transportRequestDocIDFromGit¶

Retrieves change document ID from Git repository

Description¶

This step scans the commit messages of the Git repository for a pattern to retrieve the change document ID. It is primarily made for the transportRequestUploadSOLMAN step to provide the change document ID by Git means.

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.

JenkinsCommand Line

library('piper-lib-os')

transportRequestDocIDFromGit script: this

piper transportRequestDocIDFromGit

Outputs¶

Output type	Details
commonPipelineEnvironment	custom/changeDocumentId

Executed on Jenkins Master

This step is executed on the Jenkins master only. On the master node the project's Git repository is fully available. If kubernetes is used, the Git repository would have to be stashed. Depending on the size of the repository, this would be quite expensive or not possible at all.

Administering the Change Document ID by Git Commit Messages¶

A change document documents activities in the change process. To upload an artifact into a transport request, the Solution Manager expects the ID of an assigned change document. For more information, see transportRequestUploadSOLMAN.

transportRequestDocIDFromGit allows you to retrieve the change document ID from the commit message of the Git repository of your project. This way, you can address the change document without having to change the setup of your pipeline. Please make sure that the ID is unique in the defined search range.

Specifying the Git Commit Message¶

transportRequestDocIDFromGit searches for lines that follow a defined pattern in the Git commit messages (git log) of your project. Only if necessary, specify the pattern with the label changeDocumentLabel (default=ChangeDocument). Behind the label, enter a colon, blank spaces, and the identifier.

Upload - define the change document ID

    ChangeDocument: 1000001234

Specifying the Git Commit Range¶

The Git commit messages to be considered are determined by the parameters gitFrom (default=origin/master) and gitTo (default=HEAD). The naming follows the Git revision range notation git log <gitFrom>..<gitTo>. All commit messages accessible from gitTo but not from gitFrom are taken into account. Choose the commit range accordingly, as the detection of multiple IDs causes the scan to fail.

Keep the default values HEAD and origin/master in case you want to retrieve the ID within the scope of a pull request. The default values should be sufficient provided that

you commit the change document ID into the pull request
you do not merge the origin/master before the scan

o 3d97415 (origin/master) merged last change
|
| o d99fbf7 (HEAD) feature fixes
| |
| o 5c380ea ChangeDocument: 1000001234
| |
| o 0e82d9b new feature
|/
o 4378bb4 last change

If you want to retrieve the ID from the main branch, be aware that former change document IDs may already be in the history. Adjust gitFrom so that it points to a commit before your ID definition.

steps:
  transportRequestDocIDFromGit:
    gitFrom: '4378bb4'

o 3d97415 (origin/master) merge new feature
|
o d99fbf7 feature fixes
|
o 5c380ea adjust config.yaml
|           ChangeDocument: 1000001234
|
o 0e82d9b new feature
|
o 4378bb4 merged last change

Define gitTo, if it cannot be ruled out that further document IDs have been merged in parallel.

steps:
  transportRequestDocIDFromGit:
    gitFrom: '4378bb4'
    gitTo: 'd99fbf7'

o 3d97415 (origin/master) merge new feature
|\
. o d99fbf7 feature fixes
. |
. o 5c380ea adjust config.yaml
. |           ChangeDocument: 1000001234
. |
. o 0e82d9b new feature
|/
o 4378bb4 merged last change

Parameters¶

Overview - Step¶

Name	Mandatory	Additional information
script	(yes)	reference to Jenkins main pipeline script
changeDocumentLabel	no
gitFrom	no
gitTo	no
verbose	no	activates debug output

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

Details¶

changeDocumentLabel¶

Pattern used for identifying lines holding the change document ID. The GIT commit log messages are scanned for this label

back to overview

Scope	Details
Aliases	`changeManagement/changeDocumentLabel`
Type	`string`
Mandatory	no
Default	`ChangeDocument\s?:`
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

gitFrom¶

GIT starting point for retrieving the change document and transport request ID

back to overview

Scope	Details
Aliases	`changeManagement/git/from`
Type	`string`
Mandatory	no
Default	`origin/master`
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

gitTo¶

GIT ending point for retrieving the change document and transport request ID

back to overview

Scope	Details
Aliases	`changeManagement/git/to`
Type	`string`
Mandatory	no
Default	`HEAD`
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

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

Example¶

transportRequestDocIDFromGit( script: this )