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.
How to create a new Project
There are several ways of creating new Projects:
Using the CLI when initiating a new Attestation
Using the CLI when initiating a new Attestation
During the attestation process, you can provide the name of the project the workflow belongs to and, optionally, a version.
For example, the following command will initialize an attestation associated with the project myproject and no version:
$ chainloop att init --workflow mywf --project myproject
INF Attestation initialized! now you can check its status or add materials to it
┌───────────────────────────┬──────────────────────────────────────┐
│ Initialized At │ 04 Mar 25 11:39 UTC │
├───────────────────────────┼──────────────────────────────────────┤
│ Attestation ID │ 9b94fcc1-161b-4a97-afa5-245aa1795faf │
│ Organization │ demo-org │
│ Name │ mywf │
│ Project │ myproject │
│ Version │ none │
│ Contract │ myproject-mywf (revision 1) │
│ Timestamp Authority │ http://timestamp.digicert.com │
│ Policy violation strategy │ ENFORCED │
└───────────────────────────┴──────────────────────────────────────┘
As a result, the Workflow and the Project will be associated from that moment on.
Through the User Interface
Through the User Interface
It's the first time creating a project, you will be prompted by view that looks like the following:
To create a project, click on the top right button, Create Project. You will need to fill in some information.
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.
What are 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, as the system records and evaluates the Framework’s compliance with its Requirements with each new Workflow Run for a specific project version.
How to create a Project Version?
Project versions are created when an Attestation is initialized; see for example:
chainloop att init --workflow mywf --project myproject --version v0.0.1
INF Attestation initialized! now you can check its status or add materials to it
┌───────────────────────────┬──────────────────────────────────────┐
│ Initialized At │ 05 Mar 25 09:36 UTC │
├───────────────────────────┼──────────────────────────────────────┤
│ Attestation ID │ c4dd5471-b07c-4ae1-8bd6-e9642aaff455 │
│ Organization │ demo-org │
│ Name │ mywf │
│ Project │ myproject │
│ Version │ v0.0.1 (prerelease) │
│ Contract │ myproject-mywf (revision 1) │
│ Timestamp Authority │ http://timestamp.digicert.com │
│ Policy violation strategy │ ENFORCED │
└───────────────────────────┴──────────────────────────────────────┘
The Attestation has been initialized with the flag --version to v0.0.1 and the output of the init command shows:
Version v0.0.1 (prerelease)
The CLI has created a brand new version for the project myproject with the name v0.0.1. By default, the system sets the versions as prerelease. Think about it as a work-in-progress version, not yet finished.
The specified version remains prerelease until explicitly promoted using the --release flag.
chainloop att init --workflow mywf --project myproject --version v0.0.1 --release
INF Attestation initialized! now you can check its status or add materials to it
┌───────────────────────────┬──────────────────────────────────────┐
│ Initialized At │ 05 Mar 25 09:49 UTC │
├───────────────────────────┼──────────────────────────────────────┤
│ Attestation ID │ e903906d-e937-4bf0-828a-5bc6054e7324 │
│ Organization │ demo-org │
│ Name │ mywf │
│ Project │ myproject │
│ Version │ v0.0.1 (will be released) │
│ Contract │ myproject-mywf (revision 1) │
│ Timestamp Authority │ http://timestamp.digicert.com │
│ Policy violation strategy │ ENFORCED │
└───────────────────────────┴──────────────────────────────────────┘
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.
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.
Project Details
Once a project version is created, the project details view is unblocked and can be easily accessed by just clicking on the project's name on the list of projects.
The information presented is as follows:
The current project version’s basic details, including the project name, creation date, and release dates, are displayed at the top.
Below, several tabs provide version-specific insights:
Overview: Summarizes all project workflows, their policy evaluations, and success rates across key metrics:
Compliance: Percentage of workflows passing all policies.
Status: Success rate of the last three workflow runs.
Contract: Consistency of the workflow contract version in the last three runs.
SLO: Whether the workflow has run at least once in the past 30 days.
Security: Compliance with security-related policies in the last three runs.
Workflows: A detailed view of all workflows in the project version.
Workflow Runs: List of workflow executions within the current project version.
Frameworks: Breakdown of requirement evaluations, mapping failures to specific workflows.
Policies: Raw data on policy evaluations across workflows, including status and failure insights.
Down below the General section, the Frameworks section lists a summary of the different frameworks attached to the project.
From left to right, 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, the progression of requirement evaluations over time is displayed.
How do you operate with Projects and Versions?
A drop-down is shown with several options by clicking on the three dots next to the project version.
Edit Project: Modify the basic metadata of the project.
Set X Version as Released: Marks the current version as released, similar to using the
--releaseflag withattestation initcommand.Unlist Version: Removes the current version.
Delete Project: Deletes the entire project.