Customizing DevSecOps pipelines for beginners

How DevSecOps pipelines use repositories

To build, test, and deploy your application, DevSecOps pipelines use two repositories:

• app-repo: The application repository, which contains the source code for your application.
• config-repo: The configuration repository, which contains your pipeline configuration YAML files and scripts.

In the DevSecOps sample app, these two repositories are the same. Most of the DevSecOps adopters start with this pattern. But, as you onboard more microservices, a dedicated and separate pipeline configuration repository might be needed. Because the application repository and the configuration repository are the same in the sample app, the repository is cloned twice when the pipelines are run, which can lead to errors. Therefore, it's a best practice to have a separate configuration repository to host configuration files and scripts that can be shared and reused among different DevSecOps toolchains and pipelines. For more information about customizing the configuration repository, see the advanced customization steps.

DevSecOps scripts consider the app-repo and the config-repo to be two separate repositories. The scripts clone the repositories twice during the start stage of the pipeline. These clones are referred to as the app-repo and the one-pipeline-config-repo. Each stage is run in the context of the config repo.

Option 1: Add your application repo and use the sample application repo as the configuration repo

To add your application repository to the toolchain and use the sample application repository as the configuration repository, complete the following steps:

1. In the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains, and select the toolchain that you want to edit.
2. Click Add.
3. Select where your app repo is hosted, either Gitlab or GitHub.
4. Use the default server or add a new one.
5. Enter the URL of the custom server and Personal Access Token.
6. Click Create integration.
7. Enter your application source code repository URL.
8. Click Create integration.

Next, specify the sample application repo as your configuration repo by completing the following steps:

1. In the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains, and select the toolchain that you want to edit.
2. Click pr-pipeline.
3. Click Settings and go to the Environment properties tab.
4. Edit the value of the pipeline-config-repo property to point to the sample application repository URL.
5. Go back to your CI toolchain.
6. Click ci-pipeline.
7. Click Settings and go to the Environment properties tab.
8. Edit the value of the pipeline-config-repo property to point to the sample application repository URL.

Your CI pipelines now use the sample app repo pipeline-config as your configuration repo.

Option 2: Replace the sample application repository with your own application repository

To replace the sample app repo with your own app repo, complete the following steps:

1. In the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains, and select the CI toolchain that you want to edit.
2. Find the sample application source code repository and select Configure.
3. Replace the repository URL with your application source code repository URL.
4. Click Save integration.

After you replace the sample app repo, make sure that the new app repo contains a .pipeline-config.yaml file and corresponding scripts. Either copy the .pipeline-config.yaml file and scripts from the sample app repository to your application repository, or use this sample configuration file.

Configuring the CI pipelines

After you add your application repository, you must configure the CI pipelines to work with the new repository.

Using custom scripts with DevSecOps

The pipeline-config.yaml file is the key component that orchestrates and customizes the DevSecOps pipeline behavior. The file uses scripts to build, test, and deploy your application. The file defines how the stages are configured, and which scripts are run. For more information, see custom scripts.

There are two major categories of scripts that are used by DevSecOps pipelines:

• Application-related scripts that are used to build, test, and deploy your application. These scripts are your own responsibility and out of scope for DevSecOps support. As these scripts don’t have a default implementation, you must add them to your application or configuration repository. You might need to pull the scripts from Jenkins or another source.
• Security and compliance scripts that run security and compliance scans. Most come with default scripts that you can override to use your own custom implementation.

Except for the start stage, each stage of a CI, CD, or CC pipeline can be customized with your own scripts to override the default implementation of the stage. The start stage can’t be customized with your own scripts.

Though Bash scripts are provided as samples, you can build, test, and deploy your application by using other languages like Python or Go. Make sure you're using the correct image for each stage. Refer to the Docker images in DevSecOps pipelines section.

Refer to the table Stages and tasks that summarize various stages of the CI Pipeline. The table also provides a consolidated information about whether the stage has a default reference implementation, whether it can be customized or skipped, or whether there is explicit evidence collection that is required by the stage execution.

Configuring the CD pipeline

In the DevSecOps continuous integration, continuous deployment workflow, the CI pipeline pushes updates to the inventory repository during the deploy-release stage of the CI pipeline. For more information, see the sample release.sh script.

In this workflow, multiple CI triggers and different DevSecOps CI toolchains can contribute to the same inventory repository.

Contrary to the CI pipeline, the deployment script that is used by the CD pipeline needs to be adapted from your current scripts in Jenkins, Travis, or some other platform to use the entries in the inventory repo.

This sample code shows how to retrieve information from the inventory and use it to run a Kubernetes deployment.

DevSecOps scripts location

DevSecOps pipelines come with default security and scanning tools and associated scripts.

For example, the beginning of a stage log references the default script:

scan-artifact:
  image: icr.io/continuous-delivery/pipeline/pipeline-base-ubi:3.24
  dind: true
  dind_image: icr.io/continuous-delivery/toolchains/devsecops/docker:20.10.21-dind
  abort_on_failure: false
  image_pull_policy: IfNotPresent
  script: |
    #!/bin/sh

    "/opt/commons/scan-artifact/scan.sh"

/opt/commons/scan-artifact/scan.sh is the default script.

The DevSecOps pipeline provides the path to the root folder of the commons library in an environment variable called COMMONS_PATH, which is available in all tasks and steps. To access a script that is built into the compliance base image, use the COMMONS_PATH variable with the script folder that you need:

source "${COMMONS_PATH}/<script folder in commons>/<script file name>

Refer to the table Stages and tasks that summarizes various stages of the CD Pipeline. The table also provide a consolidated information about whether the stage has a default reference implementation, whether it can be customized or skipped, or whether there is explicit evidence collection required by the stage execution.

Environment properties

DevSecOps pipelines come with predefined environment properties, but you can add as many custom properties as needed. You can access these properties values in your scripts by using the get_env command.

After you add your property and its optional default value to the pipeline or trigger, use the get_env command in your script to retrieve the property's value. The following example retrieves the my-variable property's value:

MY_VARIABLE=$(get_env my-variable "")

You can also dynamically override a property's value in a script by using the set_env command. The following example overrides the value in the my-variable property:

set_env my-variable new-value

Skipping stages

Some stages might be irrelevant. For example, you might not be building any Docker images, or you haven't implemented acceptance tests yet. If you want to skip a stage, you can edit the .pipeline-config.yaml file to include exit 0, or set the skip variable to true.

The following example adds exit 0 to skip a stage:

scan-artifact:
  image: icr.io/continuous-delivery/pipeline/pipeline-base-ubi:3.24
  dind: true
  dind_image: icr.io/continuous-delivery/toolchains/devsecops/docker:20.10.21-dind
  abort_on_failure: false
  image_pull_policy: IfNotPresent
  skip: false
  runAfter: null
  script: |
    #!/bin/sh

    exit 0
    "/opt/commons/scan-artifact/scan.sh"

Docker images in DevSecOps pipelines

By default, DevSecOps pipelines use IBM Continuous Delivery images. These images contain some of the most common tools such as Node and Java to run your scripts. You can also use other vendor's images or your own custom images that contain your preferred tools.

Docker images that are used by DevSecOps pipelines are specified in the .pipeline-config.yaml file. Each stage can use a different image.

scan-artifact:
  image: icr.io/continuous-delivery/pipeline/pipeline-base-ubi:3.24
  dind: true
  dind_image: icr.io/continuous-delivery/toolchains/devsecops/docker:20.10.21-dind
(...)