Tracking projects and getting bill of materials

This article covers how to begin tracking Projects in Tidelift from the web application and from Tidelift CLI. You will learn how to create a new project, get project API keys, get a bill of materials, and check alignment of that project with its catalog of approved open source.


Before starting this guide, you need:

  1. A Tidelift account and acccess to the Tidelift web application
  2. (CLI users only) A Tidelift User Key (from Settings > API Keys)
  3. (CLI users only) Tidelift CLI installed on your machine

1. Creating a new project in Tidelift

You will want to track each repository or application that contains open source as a project within Tidelift.

From the Tidelift web app
From Tidelift CLI
  1. Select Projects
  2. Select Track New Project
  3. Name the Project you wish to track and Save
  4. If you are not ready to upload package files and get a bill of materials, you can dismiss the prompt.
  1. Ensure you are authenticated to use Tidelift CLI with your User API Key.
  2. Use tidelift projects new in the root directory of the project. You will need to define the project name, organization, and associated catalog.

2. Generating a Project Key

To get a bill of materials using Tidelift CLI (tidelift alignment save), you will need to generate a project-specific API key. These keys are scoped to a project and necessary to use (as opposed to your User Key) because they are often integrated into a CI set-up.

From the Tidelift web app
From Tidelift CLI
  1. From Projects, select the project and select project actions and settings.
  2. Select Get Project Key.
  3. You will see your list of keys and can access the Token and Authorization information for each project.
  4. These keys can be set as the TIDELIFT_API_KEY environment variable when running tidelift alignment commands from Tidelift CLI or your CI/CD system
  1. After creating a project (see above), use tidelift projects new-key in the root project directory. This will automatically create a new key and update your TIDELIFT_API_KEY environment variable. 
  2. Ensure the key is saved to a TIDELIFT_API_KEY environment variable.

3. Getting a bill of materials and checking alignment

Each project contains a bill of materials that lists all of the open source packages used. We automatically calculate the alignment of this bill of materials with the catalog. 100% alignment indicates that a project is only using open source that is approved for use in the catalog.

Using Tidelift CLI is strongly recommended for this step. We are only able to generate an accurate bill of materials for select ecosystems through the Tidelift web app.

From the Tidelift web app
From Tidelift CLI (recommended)
  1. From Projects, select the project and select project actions and settings
  2. Select Upload FIles
  3. Upload the supported package files from the project
  1. Ensure Tidelift project and project API key has been created (see steps above)
  2. Run tidelift alignment save from the project's root directory.

    Note: If you do not need to save the bill of materials in the Tidelift web app, you can use tidelift alignment. This does not require a project API key.

What next?

At this point, you should have a bill of materials for a project and know whether or not it's in alignment with the catalog. Depending on your goals, you may choose to do any number of things:

  1. If you are a catalog admin and the project is not in alignment with the catalog, you can do this by selecting Add Packages from the Tidelift web application.
  2. If you are a developer and the project is not in alignment with the catalog, you may want to request for these packages to be added to the catalog. You can do this through the Tidelift web application or by using tidelift request --all from the CLI. Alternatively, there may be guidance from your catalog admin on how to bring this project into alignment (eg. such as by switching to an approved release).
  3. If you are trying to get more information about the project's bill of materials, you can select Bill of materials in the left-hand navigation to see and export a complete bill of materials and license data for this project.

Still need help? Contact Us Contact Us