This article shows how to use the Tidelift CLI in a Jenkins pipeline to check catalog alignment during a build stage. This allows builds to fail that include unapproved packages as part of a CI/CD process.
To get started, you will need:
- A Tidelift Subscription account
- A running Jenkins Server which can access Tidelift
With the appropriate configuration, Jenkins can use the Tidelift CLI to run an alignment as part of your Jenkins pipeline. For each Tidelift project, you can create a project and API key in Tidelift and store that key in the appropriate secrets infrastructure provided by your CI system.
An organization-level API key can also be created which is only scoped to run alignments, but works across all projects. In this example, the internal Jenkins Credential store is being use to secure the API key. Next, you need to add build stages to your Jenkins pipeline to set the Tidelift API Key, checkout code from version control, download the Tidelift CLI, and run an alignment with the Tidelift CLI.
Create a Project in Tidelift and generate an API key
After logging into the Tidelift Subscription dashboard:
- Select Projects
- Select Track New Project
- Enter the project name as it appears in version control
- When prompted, select the catalog to use or leave the default organization catalog
- Close the Upload manifest files dialog to skip manually uploading manifests
- Select the Projects actions and settings gear on the left navigation
-
Select Get Project Key then select Create Project Key
- Select Create API Key next to your project
- Copy the CI/CD usage API_KEY and note the Organization-name/project-name
In the above example:
- organization-name: "Katz Education"
- project-name: my-bitbucket-project
Add Tidelift Project API Key to credentials store
NOTE
Always check with your Jenkins and Security Administrators to ensure you are following your companies policies for securing and storing secrets.
Next set the Tidelift API key in the Jenkins credentials store. This can be done from the dashboard by selecting Manage Jenkins > Manage Credentials > Global > Add Credentials. Select Secret Text from the Kind drop down and set the credential Scope as Global per the Jenkins handbook. Next, paste the Tidelift Project API key generated in Section 1 above into the Secret field. Give the credential an ID so it can be called from a Jenkinsfile and and optionally an identifying Description.
Add pipeline build stages to check alignment with Tidelift
In Jenkins:
- Select the pipeline to use the Tidelift CLI with
- Add stages to the Jenkins pipeline to set the Tidelift API Key
- Checkout code from version control, download the Tidelift CLI
- Run an alignment with the Tidelift CLI
// Jenkinsfile example for checking dependencies from version control against a
// Tidelift Catalog
// Set build environment variable for the Tidelift API Key
// This example is for maven
pipeline {
agent any
tools {
maven 'Maven 3.8.1'
}
environment {
// Always store API keys in Jenkins credential store
// ORG key should be either an Organization API key or Project API key
TIDELIFT_ORG_API_KEY = credentials('tidelift-org-api-key')
// Only needed for automated project creation
TIDELIFT_BOT_USER_API_KEY = credentials('tidelift-bot-user-api-key')
// These are needed to run alignments and also to create the project.
// Ideally these are read from configuration in Jenkins or from local
// metadata stored in the repository being checked out.
TIDELIFT_PROJECT_NAME = 'project-name'
TIDELIFT_ORGANIZATION = 'team/<tidelift-org>'
TIDELIFT_CATALOG = 'catalog-name'
}
// Checkout code from your version control system
stages {
stage('Checkout code') {
steps {
git '<url-to-checkout>'
}
}
// Download the Tidelift CLI and make it executable
// The below URL will download the Linux version of the CLI.
// For MacOS, instead use https://download.tidelift.com/cli/tidelift_darwin
// For Windows, use https://download.tidelift.com/cli/tidelift.exe
stage('Downloading Tidelift CLI') {
steps {
sh 'curl -s -o ./tidelift
https://download.tidelift.com/cli/tidelift'
sh 'chmod +x ./tidelift'
}
}
// OPTIONAL: Create Tidelift project if it does not already exist.
// Here we are running the create command via CLI.
// If the project is not known, it will be created and logged.
// If it is known, we catch the response and move on.
// stage('Creating project if does not exist'){
// steps {
// Need to use a bot user API key in order to create the project as project
// and organization keys do not allow project creation.
// withEnv(['TIDELIFT_API_KEY=${TIDELIFT_BOT_USER_API_KEY}']){
// The command to create a new project will
// create an error if the project exists.
// Catch and move on to alignment if project exists.
// catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE'){
// sh './tidelift projects new ${TIDELIFT_PROJECT_NAME}
// --force --organization ${TIDELIFT_ORGANIZATION}
// --catalog ${TIDELIFT_CATALOG}'
// echo 'Project does not exist in Tidelift.'
// echo "Created project in Tidelift."
// }
// }
// }
// }
// Run Tidelift Catalog alignment and save output to Tidelift
// Ensure Organization or project API key is being used to run the alignment
// Optional step catches any mis-alignments reported back as to not break
// builds, but will log the mis-alignment.
stage('Running Tidelift Alignment') {
steps {
withEnv(['TIDELIFT_API_KEY=${TIDELIFT_ORG_API_KEY}']){
catchError(buildResult: 'SUCCESS', stageResult: 'FAILURE') {
sh "./tidelift alignment save --wait --project
${TIDELIFT_PROJECT_NAME}
--organization ${TIDELIFT_ORGANIZATION}"
}
}
}
}
}
}
Note: The Tidelift CLI will attempt to detect the branch of the pipeline automatically in CLI v1.3.0 and later. If the branch can not be detected, the branch will need to be specified using the branch flag. Please see the CLI reference for more information.
Once the required stages have been added to the Jenkinsfile, select Save. Test the new pipeline configuration by selecting Build Now from pipelines dashboard.
Any unapproved packages that are included in the Jenkins pipeline will cause the check to fail. The output will include a Tidelift link with more info and actions a developer can take to either request new packages or switch to already-approved releases.