Chainloop offers a structured approach to modeling Projects (software products) and their Versions. During the attestation process, you must specify the Project to which the Workflow belongs, as Projects serve as the primary way to organize Workflows. Versions, on the other hand, are optional and can remain empty.

Projects and Versions are crucial when it comes to Compliance. Compliance teams apply Requirements to these projects. Requirements can be written in a high-level language, like “container images must be signed”, “an AGPL license is forbidden”, “the software must be free from high-severity vulnerabilities”, “code repositories must be configured with least privilege principle access controls”, etc.

Your projects can be found at the Projects page in the Web UI.

The goal of this view is to show you a high-level, aggregated view of your project workflows, pieces of evidence, policy evaluations and compliance score.

You can change the project version by clicking on the version name and selecting the desired version from the dropdown menu.

At the bottom of the page, you can see the list of compliance frameworks attached to the project.

The display shows the percentage of total framework requirements being met. In the center, a detailed breakdown of individual requirements is provided, categorized by status with the following color codes:

  • Gray: No requirement evaluations are available for the current project version.
  • Green: Requirements are evaluated and passing.
  • Red: Requirements are evaluated but not passing.
  • Yellow: Requirements are evaluated but not all policies are passing.
  • Blue: Requirements are not passing, but a team member has created an exception.

Finally, on the right side, the progression of requirement evaluations over time is displayed.

Frameworks can be attached to a project at any time by clicking on the edit project button.

​
How to create a new Project

There are several ways of creating new Projects:

  • Automatically when you perform an attestation
  • Through the UI in advance

To create a project, Go ot the projects list and click, Create Project.

Create Project

  • Name: Unique name of the project in the organization. It normally matches a specific software product.
  • Description: A description of what the project is about.
  • Framework: The list of Frameworks you would like to attach the project to.

After creating the project, if you try to view its details, you’ll be notified that you must first create a project version.

​
Project Versions

Project versions help manage different releases or frozen states of your product. They are essential for Compliance, as Requirement evaluations for a project occur at the project version level.

This approach allows Chainloop to capture a snapshot of a project’s status at a specific point in time.

​
Attest to a specific version

During the attestation process, alongside providing the project you can also provide a version.

For example, the following line will initialize an attestation associated with the project myproject and version v0.0.1

chainloop att init --workflow mywf --project myproject --version v0.0.1

​
Promote a pre-release version

Note how the version in the previous output is v0.0.1 (prerelease). Think of prerelease as a work-in-progress version, not yet finished until an explicit release event is performed.

To release an existing pre-release version, you can do it either

  • Performing another attestation but this time provide the --release flag.
  • From the Web UI
chainloop att init --workflow mywf --project myproject --version v0.0.1 --release

See how the message now has changed to v0.0.1 (will be released). Once the attestation is successfully crafted and pushed, the version will be promoted to v0.0.1 when the attestation is pushed.

​
Automatically load the version

An alternative to provide the --version flag in each attestation is to use a .chainloop.yml file in your repo.

# your-project/.chainloop.yml
projectVersion: v0.1.0 # example version

The CLI, during attestation init will traverse up the directory tree and load the version from the .chainloop.yml file automatically if it exists.