Skip to content

Latest commit

 

History

History
95 lines (69 loc) · 6.63 KB

CICD-TEMPLATE.md

File metadata and controls

95 lines (69 loc) · 6.63 KB
Raw

Jenkinsfile Guidelines

This document is intended to be using in conjunction with the Jenkinsfile file to setup the CI/CD pipeline for Zowe CLI plug-in development.

Overview

The following information is intended as guidance based on our experience of what should be part of a CI/CD pipeline for a plug-in. You are free to make changes and/or configure CI/CD environments to function in your developement environment.

We describe a multi-branch pipeline in this document. In a multi-branch configuration, each branch in the GitHub repository has a pipeline. When Jenkins is configured correctly, Jenkins will auto-detect and create a new pipeline when a new branch is created in GitHub.

A pipeline must be set up with a user who has administrator access in the GitHub repository. Admin access allows the Jenkins pipeline to reflect its build status to the corresponding commit or pull request.

GitHub webhooks must be set up properly in order to allow GitHub to trigger the pipeline build when changes are committed.

Jenkinsfile Setup

Use the following information as guidance when you configure Jenkins settings in a Jenkinsfile:

Global Settings

  • RELEASE_BRANCHES: A String Array that contains the name of all release branches. Release branches are GitHub branches that we create to release a version of the product. Each branch is usually associated with a product version (for example, 1.0.0, 1.1.0, etc...) We specify the release branches so that we can perform specific tasks that only apply when we release the product. For example, building packages and releasing packages to an npm registry.

  • PIPELINE_CONTROL: An object that contains the build flags for all stages within the pipeline. This allows developers to enable or disable specific stages within the pipeline. This is used primarily to minimize the time spent running all stages when the developer is focusing on running a single stage.

  • BUILD_RESULT: A String Array that contains the defined results of the pipeline. The values are used by developer to set and check the status of the pipeline at any stage.

  • TEST_NPM_REGISTRY: The URL of a test npm registry (if applicable). The registry is intended as a temporary registry to publish the plug-in to and download the plug-in from during the smoke-test stage to validate that the plug-in is still functional.

  • TEST_RESULTS_FOLDER: The path to a directory that contains test results. Our development team decided to combine all test results in the same path.

  • UNIT_RESULTS, INTEGRATION_RESULTS, SYSTEM_RESULTS: The path to the directory that contains result of unit, integration, and system tests.

  • MASTER_RECIPIENTS_LIST: A String that contains email addresses that will receive every email generated by the pipeline.

  • ARTIFACTORY_CREDENTIALS_ID: Contains the name of a predefined credential within Jenkins credential store. This credential must be defined with a user that has permission read and write to a Bintray registry. The artifactory is used for installing Zowe CLI and plug-ins from a Bintray registry and to to publish the plug-in to the registry.

  • ARTIFACTORY_EMAIL: An email address used in conjunction with the ARTIFACTORY_CREDENTIAL_ID to log in to the artifactory registry.

Pipeline Agent

ca-jenkins-agent: The ca-jenkins-agent is a Jenkins label which is predefined to represent a Jenkins agent. A Jenkins agent is a Linux machine that is integrated with Jenkins server. This agent is where all of the pipeline operations run. The agent must be set up with the following configuration:

  • Must be configured so that the keytar Node module can be used. See Jenkins Machine Information for information about how to configure the build agent for keytar.
  • A Jenkins user must be defined.
  • The agent is connected to a Jenkins server.
  • Allow jenkins users to operate with the "sudo" privilege.
  • The agent can communicate with all external system that are used for System tests.
  • The agent can communicate with the registry that you defined for publishing.

Note: Pipeline developers are responsible for maintaining and cleaning up the build environment.

Pipeline Stages

Review the following descriptions to understand what occurs in each stage of the CI/CD pipeline:

  • Check for CI skip: This stage responsible for checking the latest commit statement for the "ci skip" string. When the string is located, set the CI skip flag skips all of the CI stages.
  • Install Zowe CLI:
    • Because this CI/CD template is intended for Zowe CLI plug-in development, we assume that you will always need to install a copy of Zowe CLI in to the build environment to prepare for later stages.
    • We decided to install Zowe CLI on every build to ensure that we always have the latest version of Zowe CLI. However this stage can be remove if the user chooses to pre-install Brightside in the Linux build agent.
  • Install Dependencies: In this stage, we issue the yarn install command to install all npm dependencies defined in the package.json file of the plug-in.
  • Build: In this stage, we issue the yarn build command and archive built artifacts.
  • Unit Test: In this stage, we perform unit tests and record the results so that we can monitor the progress.
  • Integration Test: In this stage, integration tests are run and results are recorded. Developers must perform all of the necessary setup steps for the integration tests.
  • System Test: This stage is where the system tests run. Developers must perform all of the necessary setup steps for the system tests.
  • Bump Version:
    • In our project, beside the branches specified in the RELEASE_BRANCHES, we set the building branch version to the following format: major.minor.path-branchName.buildNumber
    • This format allows us to later deploy the package for testing. We can also determine which build the package came from by tracing back to the code commit in GitHub.
  • Deploy: Deploy the plug-in package to a designated registry.
  • Smoke Test: Install the plug-in package to the pre-installed Zowe CLI instance and run a simple command to ensure that the plug-in installs and runs properly.
  • Post build: Send an email to the development team to inform them of the progress of the build along with any other information.