Projects and Versions
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.
- 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.
To create a project, Go ot the projects list and click, 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.
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:
As a result, the Workflow and the Project will be associated from that moment on.
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
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
--releaseflag. - From the Web UI
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.
The CLI, during attestation init will traverse up the directory tree and load the version from the .chainloop.yml file automatically if it exists.