jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2024-12-12 10:55:20 +02:00
Code Issues Releases Activity

solman upload split git documentation (#2831)

Browse Source 
* Split git commit message scan from solman upload
This commit is contained in:
Roland Stengel 2021-06-10 10:16:22 +02:00 committed by GitHub
parent c22e0a1f0e
commit 1eab39d847
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 253 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
cmd/transportRequestDocIDFromGit_generated.go
View File

@ -63,7 +63,8 @@ func TransportRequestDocIDFromGitCommand() *cobra.Command {
var createTransportRequestDocIDFromGitCmd = &cobra.Command{
Use: STEP_NAME,
Short: "Retrieves change document ID from Git repository",
Long: `Scans the commit messages of the Git repository for a pattern to retrieve the change document ID.`,
Long: `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.`,
PreRunE: func(cmd *cobra.Command, _ []string) error {
startTime = time.Now()
log.SetStepName(STEP_NAME)

3
cmd/transportRequestReqIDFromGit_generated.go
View File

@ -63,7 +63,8 @@ func TransportRequestReqIDFromGitCommand() *cobra.Command {
var createTransportRequestReqIDFromGitCmd = &cobra.Command{
Use: STEP_NAME,
Short: "Retrieves the transport request ID from Git repository",
Long: `Scans the commit messages of the Git repository for a pattern to retrieve the transport request ID.`,
Long: `This step scans the commit messages of the Git repository for a pattern to retrieve the transport request ID.
It is primarily made for the transportRequestUploadSOLMAN step to provide the transport reques ID by Git means.`,
PreRunE: func(cmd *cobra.Command, _ []string) error {
startTime = time.Now()
log.SetStepName(STEP_NAME)

107
documentation/docs/steps/transportRequestDocIDFromGit.md Normal file
View File

@ -0,0 +1,107 @@
# ${docGenStepName}
## ${docGenDescription}
!!! note "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](transportRequestUploadSOLMAN.md).
`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.
```yaml
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.
```yaml
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
```
## ${docGenParameters}
## ${docGenConfiguration}
## ${docJenkinsPluginDependencies}
## Example
```groovy
transportRequestDocIDFromGit( script: this )
```

111
documentation/docs/steps/transportRequestReqIDFromGit.md Normal file
View File

@ -0,0 +1,111 @@
# ${docGenStepName}
## ${docGenDescription}
!!! note "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 Transport Request ID by Git Commit Messages
The `transport request ID` identifies a container in the ABAP development system that can be used to document and transport changes within the landscape.
If you upload your pipeline artifacts into such a container, please provide the transport request ID in an upload step.
See [transportRequestUploadSOLMAN](transportRequestUploadSOLMAN.md).
With `transportRequestReqIDFromGit` you can retrieve the transport request ID from the commit message of the Git repository of your project. This way, you can address the transport request 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
`transportRequestReqIDFromGit` 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 _transportRequestLabel_ (default=`TransportRequest`).
Behind the label, enter a colon, blank spaces, and the identifier.
```
Upload - define the transport request ID
TransportRequest: ABCD10005E
```
### 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 transport request ID into the pull request
* you do not merge the `origin/master` before the scan
* you do not change the transport request ID while developing
This way, only the commits (`HEAD`) that have not yet entered the main branch `origin/master` are scanned.
```
o 3d97415 (origin/master) merged last change
|
| o d99fbf7 (HEAD) feature fixes
| |
| o 5c380ea TransportRequest: ABCD10001E
| |
| o 0e82d9b new feature
|/
o 4378bb4 last change
```
If you want to retrieve the ID from the main branch, be aware that former transport request IDs may already be in the history.
Adjust _gitFrom_ so that it points to a commit before your ID definition.
```yaml
steps:
transportRequestReqIDFromGit:
gitFrom: '4378bb4'
```
```
o 3d97415 (origin/master) merge new feature
|
o d99fbf7 feature fixes
|
o 5c380ea adjust config.yaml
| TransportRequest: ABCD10001E
|
o 0e82d9b new feature
|
o 4378bb4 merged last change
```
Define _gitTo_, if it cannot be ruled out that further transport request IDs have been merged in parallel.
```yaml
steps:
transportRequestReqIDFromGit:
gitFrom: '4378bb4'
gitTo: 'd99fbf7'
```
```
o 3d97415 (origin/master) merge new feature
|\
. o d99fbf7 feature fixes
. |
. o 5c380ea adjust config.yaml
. | TransportRequest: ABCD10001E
. |
. o 0e82d9b new feature
|/
o 4378bb4 merged last change
```
## ${docGenParameters}
## ${docGenConfiguration}
## ${docJenkinsPluginDependencies}
## Example
```groovy
transportRequestReqIDFromGit( script: this )
```

83
documentation/docs/steps/transportRequestUploadSOLMAN.md
View File

@ -7,34 +7,33 @@
* You have an SAP Solution Manager user account and the roles required for uploading. See [SAP Solution Manager Administration](https://help.sap.com/viewer/c413647f87a54db59d18cb074ce3dafd/7.2.12/en-US/11505ddff03c4d74976dae648743e10e.html).
* You have a change document to which your transport request is coupled.
* You have a transport request, which is the target container of the upload.
* You have installed the Change Management Client with the needed certificates.
* You have installed the Change Management Client with the needed certificates. See [Change Management Client](#Change Management Client).
## Change Management Client
The Change Management Client (CM Client) handles the access to SAP Solution Manager.
The CM Client is a software running under Linux, which can initiate basic change management tasks
in the Solution Manager as well as in the CTS. The client is used by default
as a [Docker image](https://hub.docker.com/r/ppiper/cm-client),
as a [Docker image](https://hub.docker.com/r/ppiper/cm-client),
but can also be installed as a [command line tool](https://github.com/SAP/devops-cm-client).
### Certificates
!!! note "Certificates"
It is expected that the Solution Manager endpoint is secured by SSL and sends a certificate accordingly.
The CM Client verifies the certificate. If the publisher of this certificate is unknown, the connection will be rejected.
The CM Client uses the underlying JDK procedures for the verification.
Accordingly, the issuer must be specified in the truststore of the JDK.
It is expected that the Solution Manager endpoint is secured by SSL and sends a certificate accordingly.
The certificate is verified by the CM Client. If the publisher of this certificate is unknown,
the connection will be rejected. The client implemented in Java uses
the underlying JDK procedures for the verification. Accordingly, the issuer must be specified in the
truststore of the JDK. In the case of the [Docker image](https://hub.docker.com/r/ppiper/cm-client)
a clone of the image must be created with the necessary certificate added to its truststore.
In the case of the immediate [command line tool](https://github.com/SAP/devops-cm-client),
only the truststore of the environment needs to be extended.
Create a clone of the image and add the necessary certificate to its truststore in case you use the [Docker image](https://hub.docker.com/r/ppiper/cm-client).
Extend the truststore of the environment with the necessary certificate in the case you use the immediate [command line tool](https://github.com/SAP/devops-cm-client).
## Specifying the Change document and transport request
## Specifying the Change Document and Transport Request
The target of the upload is a Transport Request, which is determined by the identifiers (ID)
of the Request and the associated Change Document.
`transportRequestUploadSOLMAN` allows to set these IDs by parameter or to use Git commit messages.
As an additional option, IDs can be passed in via the Common Pipeline Environment. For example through a
step that generates the IDs or obtains them differently.
The target of the upload is a transport request and the associated change document.
Both objects are identified by identifiers (ID).
`transportRequestUploadSOLMAN` allows you to set IDs by parameter.
Alternatively, you can pass the IDs through the Common Pipeline Environment.
For example, by performing a step that generates the IDs or obtains them differently.
See [transportRequestDocIDFromGit](transportRequestDocIDFromGit.md) and [transportRequestReqIDFromGit](transportRequestReqIDFromGit.md)
### By Step Parameter
@ -68,49 +67,15 @@ transportRequestUploadSOLMAN(
)
```
### By Git Commit Message
If the identifiers are neither defined as step parameters nor by the Common Pipeline Environment,
the Git commit messages (`git log`) of the project are searched for lines that follow a defined pattern.
The pattern is specified by the label _changeDocumentLabel_ (default=`ChangeDocument`) resp.
_transportRequestLabel_ (default=`TransportRequest`). Behind the label a colon,
any blanks and the identifier are expected.
```
Release - define IDs for upload to Solution Manager
ChangeDocument: 1000001234
TransportRequest: ABCD10005E
```
The IDs dont need to be defined in the same commit message.
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 representation `git log <gitFrom>..<gitTo>`.
All commit messages accessible from _gitTo_ but not from _gitFrom_ are taken into account. If the scanner
detects multiple IDs, it fails. So the commit range has to be chosen accordingly.
In case of a pull request of a feature branch, the default should be sufficient as long as the transport request
isn't changed. Only the commits (`HEAD`) that have not yet entered the main branch `origin/master` would be scanned.
If uploading from the main branch, it must be assumed that former change document and transport request IDs
are already contained in the history. In this case the new IDs should be maintained in the `HEAD` and
_gitFrom_ be set to `HEAD~1`.
```yaml
general:
changeManagement:
git:
from: 'HEAD~1'
```
## Common Pipeline Environment
If `changeDocumentId` and `transportRequestId` are determined during runtime via the Git commit messages, they are entered into the `commonPipelineEnvironment` and can be retrieved accordingly.
With OS Piper you can use the steps [transportRequestDocIDFromGit](transportRequestDocIDFromGit.md) and [transportRequestReqIDFromGit](transportRequestReqIDFromGit.md) to obtain the `changeDocumentId` and `transportRequestId` values from your Git commit messages.
The steps enter the IDs into the `commonPipelineEnvironment`, in turn, the upload step `transportRequestUploadSOLMAN` picks them up from there.
```
this.commonPipelineEnvironment.getValue('changeDocumentID')
this.commonPipelineEnvironment.getValue('transportRequestID')
```groovy
transportRequestDocIDFromGit( script: this )
transportRequestReqIDFromGit( script: this )
transportRequestUploadSOLMAN( script: this, ... )
```
## ${docGenParameters}
@ -127,8 +92,8 @@ transportRequestUploadSOLMAN(
endpoint: 'https://example.org/cm/solman/endpoint'
applicationId: 'ABC',
uploadCredentialsId: "SOLMAN_CRED_ID"
changeDocumentId: '12345678',
transportRequestId: '87654321',
changeDocumentId: '1000001234',
transportRequestId: 'ABCD10005E',
filePath: '/path/file.ext',
cmClientOpts: '-Dkey=value'
)

3
documentation/mkdocs.yml
View File

@ -144,8 +144,11 @@ nav:
- testsPublishResults: steps/testsPublishResults.md
- tmsUpload: steps/tmsUpload.md
- transportRequestCreate: steps/transportRequestCreate.md
- transportRequestDocIDFromGit: steps/transportRequestDocIDFromGit.md
- transportRequestRelease: steps/transportRequestRelease.md
- transportRequestReqIDFromGit: steps/transportRequestReqIDFromGit.md
- transportRequestUploadFile: steps/transportRequestUploadFile.md
- transportRequestUploadSOLMAN: steps/transportRequestUploadSOLMAN.md
- uiVeri5ExecuteTests: steps/uiVeri5ExecuteTests.md
- vaultRotateSecretId: steps/vaultRotateSecretId.md
- whitesourceExecuteScan: steps/whitesourceExecuteScan.md

3
resources/metadata/transportRequestDocIDFromGit.yaml
View File

@ -2,7 +2,8 @@ metadata:
name: transportRequestDocIDFromGit
description: "Retrieves change document ID from Git repository"
longDescription: |
Scans the commit messages of the Git repository for a pattern to retrieve the change document ID.
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.
spec:
inputs:
params:

3
resources/metadata/transportRequestReqIDFromGit.yaml
View File

@ -2,7 +2,8 @@ metadata:
name: transportRequestReqIDFromGit
description: "Retrieves the transport request ID from Git repository"
longDescription: |
Scans the commit messages of the Git repository for a pattern to retrieve the transport request ID.
This step scans the commit messages of the Git repository for a pattern to retrieve the transport request ID.
It is primarily made for the transportRequestUploadSOLMAN step to provide the transport reques ID by Git means.
spec:
inputs:
params: