github.com/jaylevin/jenkins-library@v1.230.4/documentation/docs/steps/transportRequestDocIDFromGit.md (about)

     1  # ${docGenStepName}
     2  
     3  ## ${docGenDescription}
     4  
     5  !!! note "Executed on Jenkins Master"
     6      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.
     7  
     8  ## Administering the Change Document ID by Git Commit Messages
     9  
    10  A `change document` documents activities in the change process.
    11  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).
    12  
    13  `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.
    14  Please make sure that the ID is unique in the defined search range.
    15  
    16  ### Specifying the Git Commit Message
    17  
    18  `transportRequestDocIDFromGit` searches for lines that follow a defined pattern in the Git commit messages (`git log`) of your project.
    19  Only if necessary, specify the pattern with the label _changeDocumentLabel_ (default=`ChangeDocument`).
    20  Behind the label, enter a colon, blank spaces, and the identifier.
    21  
    22  ```
    23  Upload - define the change document ID
    24  
    25      ChangeDocument: 1000001234
    26  ```
    27  
    28  ### Specifying the Git Commit Range
    29  
    30  The Git commit messages to be considered are determined by the parameters _gitFrom_ (default=`origin/master`) and _gitTo_ (default=`HEAD`).
    31  The naming follows the Git revision range notation `git log <gitFrom>..<gitTo>`.
    32  All commit messages accessible from _gitTo_ but not from _gitFrom_ are taken into account.
    33  Choose the commit range accordingly, as the detection of multiple IDs causes the scan to fail.
    34  
    35  Keep the default values `HEAD` and `origin/master` in case you want to retrieve the ID within the scope of a pull request.
    36  The default values should be sufficient provided that
    37  
    38  * you commit the change document ID into the pull request
    39  * you do not merge the `origin/master` before the scan
    40  
    41  ```
    42  o 3d97415 (origin/master) merged last change
    43  |
    44  | o d99fbf7 (HEAD) feature fixes
    45  | |
    46  | o 5c380ea ChangeDocument: 1000001234
    47  | |
    48  | o 0e82d9b new feature
    49  |/
    50  o 4378bb4 last change
    51  ```
    52  
    53  If you want to retrieve the ID from the main branch, be aware that former change document IDs may already be in the history.
    54  Adjust _gitFrom_ so that it points to a commit before your ID definition.
    55  
    56  ```yaml
    57  steps:
    58    transportRequestDocIDFromGit:
    59      gitFrom: '4378bb4'
    60  ```
    61  
    62  ```
    63  o 3d97415 (origin/master) merge new feature
    64  |
    65  o d99fbf7 feature fixes
    66  |
    67  o 5c380ea adjust config.yaml
    68  |           ChangeDocument: 1000001234
    69  |
    70  o 0e82d9b new feature
    71  |
    72  o 4378bb4 merged last change
    73  ```
    74  
    75  Define _gitTo_, if it cannot be ruled out that further document IDs have been merged in parallel.
    76  
    77  ```yaml
    78  steps:
    79    transportRequestDocIDFromGit:
    80      gitFrom: '4378bb4'
    81      gitTo: 'd99fbf7'
    82  ```
    83  
    84  ```
    85  o 3d97415 (origin/master) merge new feature
    86  |\
    87  . o d99fbf7 feature fixes
    88  . |
    89  . o 5c380ea adjust config.yaml
    90  . |           ChangeDocument: 1000001234
    91  . |
    92  . o 0e82d9b new feature
    93  |/
    94  o 4378bb4 merged last change
    95  ```
    96  
    97  ## ${docGenParameters}
    98  
    99  ## ${docGenConfiguration}
   100  
   101  ## ${docJenkinsPluginDependencies}
   102  
   103  ## Example
   104  
   105  ```groovy
   106  transportRequestDocIDFromGit( script: this )
   107  ```