Using Tidelift with CircleCI

This article shows how to use the Tidelift CLI with CircleCI Pipelines to check catalog alignment during a build stage. This allows builds to fail that include unapproved packages as of a CI/CD process.

To get started, you will need:

  • A Tidelift Subscription (Please contact us if you are interested in learning more about Tidelift)
  • A CircleCI account which can access Tidelift

With the appropriate configuration, CircleCI Pipelines can use the Tidelift CLI to run an alignment as part of your 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 API key is stored as a secret variable in the pipeline settings. Next, you need to add steps to your pipeline job that 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 in the Tidelift webapp

After logging into the Tidelift Subscription dashboard:

  1. Select Projects
  2. Select Create New Project
  3. Enter the project name and remember that spaces, periods, or slashes are not valid naming characters in project names
  4. When prompted, select the catalog you want the project to align with.


  5. Close the Upload manifest files dialog to skip manually uploading manifests
  6. Select the Projects actions and settings gear on the left navigation
  7. Select Get Project Key then select Create Project Key


  8. Copy the CI/CD usage API_KEY and note the Organization-name/project-name


In the above example:

  • organization-name: "souza-weisberg-holdings"
  • project-name: "circleci-test-project"

Add the API Key to the CircleCI Pipeline Workflow


Always check with your Security Administrators to ensure you are following your companies policies for securing and storing secrets.

In this example, the Tidelift API key will be secured as a context. This can be done under Organization Settings > Contexts. Create a context and then create an environment variable for the Tidelift API key. Name the variable and past the API key into the value field. 


Add pipeline job step to check alignment with Tidelift

In CircleCI:

  1. Select the pipeline to use the Tidelift CLI witH
  2. Add a job with the steps to set the Tidelift API Key
  3. Checkout code from version control
  4. Download the Tidelift CLI
  5. Run an alignment with the Tidelift CLI.

config.yml example:

# Use the latest 2.1 version of CircleCI pipeline process engine.

# See:

version: 2.1

# Define a job to be invoked later in a workflow.

# See:



# Specify the execution environment. You can specify an image from Dockerhub
or use one of our Convenience Images from CircleCI's Developer Hub.

# See:


- image: cimg/ruby:2.7.1-node

# Add steps to the job

# See:


- checkout

- run: curl -o tidelift

- run: chmod +x tidelift

- run: ./tidelift alignment save --wait

# Invoke jobs via workflows

# See:




- tidelift-alignment:

context: tidelift-api-key

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 job steps have been added to the pipeline, select Save. Test the new pipeline configuration by selecting run workflow from start in the pipeline dashboard. Any unapproved packages that are included in the 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.

Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.

Articles in this section