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

     1  # Project "Piper" general purpose pipeline
     2  
     3  The pipeline consists of a sequence of stages where each contains a number of individual steps.
     4  
     5  ## First step: Pull Request Pipeline
     6  
     7  In order to validate pull-requests to your GitHub repository you need to perform two simple steps:
     8  
     9  ### 1. Create Pipeline configuration
    10  
    11  Create a file `.pipeline/config.yml` in your repository (typically in `master` branch) with the following content:
    12  
    13  ``` YAML
    14  general:
    15    buildTool: 'npm'
    16  ```
    17  
    18  !!! note "buildTool"
    19      Please make sure that you specify the correct build tool.
    20      Following are currently supported:
    21  
    22      * `docker`
    23      * `kaniko`
    24      * `maven`
    25      * `mta`
    26      * `npm`
    27  
    28      If your build tool is not in the list you can still use further options as described for [Pull-Request Voting Stage](prvoting.md)
    29  
    30  ### 2. Create Jenkinsfile
    31  
    32  Create a file called `Jenkinsfile` in the root of your repository (typically in `master` branch) with the following content:
    33  
    34  ```groovy
    35  @Library('piper-lib-os') _
    36  
    37  piperPipeline script: this
    38  ```
    39  
    40  **There is typically no need to further touch this file**
    41  
    42  !!! note "Using custom defaults"
    43      It is possible to overwrite/extend the pipeline defaults with custom defaults.
    44  
    45      ```
    46      piperPipeline script: this, customDefaults: ['myCustomDefaults.yml']
    47      ```
    48  
    49      You find more details about the custom defaults in the [configuration section](../configuration.md)
    50  
    51  !!! warning "using dedicated versions"
    52      It is possible to use a fixed version of the library using e.g.
    53  
    54      ```
    55      @Library('piper-lib-os@v1.222.0') _
    56      ```
    57  
    58      **Make sure to only use valid git tags as versions!**
    59  
    60  ## Second step: Prepare pipeline for your main branch
    61  
    62  Extend your configuration to also contain git ssh credentials information.
    63  
    64  Your `.pipeline/config.yml` should then look like:
    65  
    66  ``` YAML
    67  general:
    68    buildTool: 'npm'
    69    gitSshKeyCredentialsId: 'credentials-id-in-jenkins'
    70  ```
    71  
    72  !!! note "gitSshKeyCredentialsId"
    73      The pointer to the Jenkins credentials containing your ssh private key is an important part of the pipeline run.
    74      The credentials are for example required to push automatic versioning information to your GitHub repository.
    75  
    76  ## Subsequent steps: Configure individual stages
    77  
    78  The stages of the pipeline can be configured individually.
    79  As a general rule of thumb, only stages with an existing configuration are executed.
    80  
    81  If no dedicated configuration is required for a step, the precence of relevant files in the repository trigger the step execution.
    82  
    83  **This smart and context-aware way of configuration** allows you an iterative approach to configuring the individual steps.
    84  
    85  The pipeline comprises following stages:
    86  
    87  ### Init
    88  
    89  This stage takes care that the pipeline is initialized correctly.
    90  It will for example:
    91  
    92  * Check out the GitHub repository
    93  * Set up the overall pipeline configuration and perform basic checks
    94  * Identify which pipeline stages to execute based on the configuration and file patterns
    95  * Perform automatic versioning of the software artifact in case the `master` branch pipeline is executed.
    96  
    97  You find details about this stage on  [**Init Stage** Details](init.md)
    98  
    99  ### Pull-Request Voting
   100  
   101  This stage is responsible for validating pull-requests, see also above.
   102  
   103  You find further details about this stage on the page [**Pull-Request Voting**](prvoting.md).
   104  
   105  ### Build
   106  
   107  In this stage the build of the software artifact is performed.
   108  The build artifact will be `stash`ed for use in subsequent stages. For `Docker` builds the build result will be uploaded to a container registry (as per your configuration).
   109  
   110  Afterwards the results of static checks & unit tests are published on the Jenkins.
   111  
   112  You find details about this stage on the page [**Build**](build.md).
   113  
   114  ### Additional Unit Tests
   115  
   116  In this stage additional unit-like tests are executed which should not run during the build.
   117  
   118  Currently, this stage holds the execution of a Karma runner which allows for
   119  
   120  * qUnit tests
   121  * OPA5 (One Page Acceptance tests) for SAPUI5
   122  
   123  You find details about this stage on the page [**Additional Unit Tests**](additionalunittests.md).
   124  
   125  ### Integration
   126  
   127  The [Integration stage](integration.md) allows to run test based on maven, npm, or a custom integration test script.
   128  If more flexibility is required, consider using the [stage extension mechanism](../extensibility.md).
   129  
   130  You find details about this stage on the page [**Integration**](integration.md).
   131  
   132  ### Acceptance
   133  
   134  In this stage the application/service is typically deployed and automated acceptance tests are executed.
   135  
   136  This is to make sure that
   137  
   138  * new functionality is tested end-to-end
   139  * there is no end-to-end regression in existing functionality
   140  
   141  You find details about this stage on the page [**Acceptance**](acceptance.md).
   142  
   143  ### Security
   144  
   145  This stage can run security checks using Checkmarx, Synopsys Detect, Fortify and WhiteSource.
   146  
   147  You find details about this stage on the page [**Security**](security.md).
   148  
   149  ### Performance
   150  
   151  The stage will execute a Gatling test, if the step `gatlingExecuteTests` is configured.
   152  
   153  You find details about this stage on the page [**Performance**](performance.md).
   154  
   155  ### Compliance
   156  
   157  The stage will execute a SonarQube scan, if the step `sonarExecuteSan` is configured.
   158  
   159  You find details about this stage on the page [**Compliance**](compliance.md).
   160  
   161  ### Confirm
   162  
   163  The [Confirm stage](confirm.md), if executed, stops the pipeline execution and asks for manual confirmation before proceeding to the stages _Promote_ and _Release_.
   164  
   165  ### Promote
   166  
   167  This stage is responsible to promote build artifacts to an artifact repository / container registry where they can be used from production deployments.
   168  
   169  You find details about this stage on the page [**Promote**](promote.md).
   170  
   171  ### Release
   172  
   173  This stage is responsible to release/deploy artifacts into your productive landscape.
   174  
   175  You find details about this stage on the page [**Release**](release.md).