Overview
A CI/CD pipeline has many stages: build, test, scan, release, and deploy to one or more environments. Chainloop does not need one large attestation for the full pipeline. Each stage is a Chainloop workflow. Each time a stage runs, it sends a signed attestation with its evidence, and Chainloop records it as a workflow run. Chainloop connects the workflow runs of the stages through the evidence that they share, for example the same container image. This guide shows how to:- Model each stage as a workflow with its own contract.
- Instrument each stage to send attestations to the same project and version.
- Link the stages, so you can follow the provenance from end to end.
- Add a control gate that stops a deployment when the upstream evidence is missing or does not pass its policies.
Step 1: Model Each Stage as a Workflow
A workflow is one source of attestations. A workflow can map to any CI/CD process from any stage of your SDLC, for example build, SAST, DAST, vulnerability scan, release, or deploy. This guide uses the workflowsci, deploy-staging, and deploy-production. Each time it runs, its attestation creates a new workflow run.
For each stage, create a contract, then create a workflow that uses it:
- Create a contract. The contract defines the pieces of evidence (materials) that the workflow must attest, and the policies that Chainloop runs on them.
- Create the workflow with the contract. Each attestation of the workflow then uses the contract. See Associating workflows to contracts.
Step 2: Instrument Each Stage to Send Attestations
Each stage of your pipeline sends its evidence to Chainloop with the attestation lifecycle of the Chainloop CLI. Add these steps to the CI/CD job of the stage:- Install the CLI. See Install the CLI.
- Authenticate. Set an API token in the
CHAINLOOP_TOKENenvironment variable. In GitHub Actions and GitLab CI, you can use keyless attestation with the OIDC token of the runner instead. - Start the attestation with
chainloop attestation init. Give the workflow, the project, and the project version. - Add the evidence with
chainloop attestation add, for example the container image, the SBOM, or the test results. - Send the attestation with
chainloop attestation push. If the job fails before the push, runchainloop attestation resetto mark the workflow run as failed.
ci stage:
Set the Same Project and Version in Every Stage
The project and the version that you give tochainloop attestation init are important. They decide where the workflow runs of all your stages go.
The project version is one way to group workflow runs and evidence. The project version shows every workflow run attested to it, with the evidence of each run. It does not matter which workflow sent the attestation, or when.
When all the stages attest to the same project version, it shows the runs, evidence, and policy results of all the stages together. Chainloop also evaluates compliance requirements on the project version, so the evidence of each stage counts toward them.
You set the project version during the attestation, in one of two ways:
-
The
--versionflag. Give the same--projectand--versiontochainloop attestation initin every stage. Chainloop creates the version if it does not exist. -
A
.chainloop.ymlfile. Put the version in a.chainloop.ymlfile in the repository. The CLI reads it duringchainloop attestation init, so the stages do not need the--versionflag. See Automatically load the version.
Step 3: Link the Stages
The project version groups the workflow runs and evidence of a release. Links are another way to group workflow runs and evidence. Chainloop creates a link automatically when two workflow runs attest the same material. A link connects workflow runs and evidence inside a project version, and also across project versions and projects. Use links to model the traditional stages of a pipeline, for example pull request, build, test, release, and deploy. Each stage attests a material that the next stage also attests, and the shared material connects the two stages. Chainloop stores evidence as a graph. Chainloop references each material by its digest, so two attestations that contain the same material point to the same node in the graph. A stage does not need to know about the other stages. It only needs to add a material that the other stages also add. Evidence Graph explains how Chainloop connects the nodes. You can link the stages in different ways:
To link by artifact, add the image to the attestation in the CI stage and in the CD stage:
STRING material in both stages:
build-id material does not need to be in the contracts. You can add it as a contract-less material.
A CONTAINER_IMAGE material records the digest of the image, not only the tag. Two stages that use the same tag for different images do not link.
Remote state does not link stages. Remote state lets several jobs add evidence to the same attestation of one workflow run. Use it for parallel jobs or for stateless runners such as Dagger. Chainloop expires a workflow run that is not finished one hour after it starts. Do not keep one run open across the stages of a pipeline. Use one workflow per stage, and link the stages as this step shows.
Step 4: Explore the End-to-End Provenance
When the stages share a material, you can go from the artifact to all the workflow runs that attested it.- In the Chainloop UI: open the artifact or a workflow run and select the Provenance tab. The graph shows the artifact and the workflow runs that reference it. You can also search the graph by the digest of the artifact on the Trust Hub page, under Labs in the sidebar.
- With the CLI: run
chainloop discoverwith the digest of the artifact:
digest is the digest of the attestation, not of the image. Its metadata shows the workflow, the project, the version, and the policy results of the run:
Step 5: Add a Control Gate Before Deployment
A control gate is a policy withgate: true. When a gated policy fails, chainloop attestation push returns a non-zero exit code and your pipeline stops before the deployment. For how to turn on enforcement and how to record a bypass, see Control Gates.
Chainloop gives you four types of checks for a CD stage:
Custom policies that call the
chainloop.* built-in functions need a paid plan. You can combine all the checks in the same CD contract. The rest of this guide uses upstream-check.
upstream-check evaluates a material of the CD attestation. It looks for runs of the named workflow, in the same project, that attested a material with the same digest. By default, the latest of those runs must exist and must have no policy violations. Its inputs change this behavior:
runs: allchecks all the runs that attested the material, not only the latest one.require_run: "false"passes when no run attested the material.fail_on: policy-gate-violationsfails only on violations of gated policies.
upstream-check works with any material type, so it works with the artifact link and with the STRING link. It matches the material digest and the project, not the project version.
End-to-End Example
This example has two stages. The CI stage builds and attests a container image. The CD stage deploys the image only when the CI stage attested it with no policy violations.CI Stage
The CI contract requires a container image. Its policies check that the image has a signature and that it does not use thelatest tag.
ci workflow:
CD Stage
The CD contract also requires the container image. Theupstream-check policy checks that the latest ci run that attested this image has no policy violations. gate: true makes the policy a control gate.
Build Once, Deploy Many
The CI stage builds the artifact once. You can deploy the same artifact many times, in different pipeline runs and to different environments. Each deployment is a run of a CD workflow, for exampledeploy-staging and then deploy-production. Each run adds the same image, so all the runs link to the same digest and to the same CI attestation. The CD pipeline does not need the CI build ID or the CI pipeline run.
To also record where each artifact runs, use deployment tracking.
Advanced: Manage Contracts for Many Applications
When a central team manages the contracts for many applications, these features help:- “At Least One Of” material groups accept the output of different tools for the same need, for example any one of several vulnerability scanners. One contract can then serve teams that use different tools.
- Workflow templates bundle a contract and its inputs into a reusable blueprint, so each team creates its workflows from the same definition.
Next Steps
- Control Gates: turn on enforcement and record bypasses
- Built-in policies: all the policies that you can attach to a contract
- Custom policies: write your own gate with the built-in functions
- Projects and Versions: manage the versions that your stages attest to
