> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Your CI/CD Pipeline

> Model each stage of your CI/CD pipeline as a Chainloop workflow, link the stages through a shared artifact, and gate deployments on upstream evidence.

## 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](https://docs.chainloop.dev/concepts/attestations.md) 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:

1. Model each stage as a [workflow](https://docs.chainloop.dev/concepts/workflows.md) with its own [contract](https://docs.chainloop.dev/concepts/contracts.md).
2. Instrument each stage to send attestations to the same [project and version](https://docs.chainloop.dev/concepts/projects-versions.md).
3. Link the stages, so you can follow the provenance from end to end.
4. Add a [control gate](https://docs.chainloop.dev/concepts/control-gates.md) that stops a deployment when the upstream evidence is missing or does not pass its policies.

The diagram shows the model that this guide builds. A CI workflow builds a container image. Two CD workflows deploy the same image. The image digest (the hash of the image content) connects the three attestations in the same project version.

```mermaid theme={"dark"}
flowchart LR
  subgraph pv[Project my-app, version v1.4.0]
    ci[Workflow ci<br/>contract my-app-ci] --> img((Container image<br/>sha256:...))
    img --> stg[Workflow deploy-staging<br/>contract my-app-cd]
    img --> prd[Workflow deploy-production<br/>contract my-app-cd]
  end
```

## 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 workflows `ci`, `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:

1. **Create a [contract](https://docs.chainloop.dev/concepts/contracts.md).** The contract defines the pieces of evidence (materials) that the workflow must attest, and the [policies](https://docs.chainloop.dev/concepts/policies.md) that Chainloop runs on them.
2. **Create the workflow with the contract.** Each attestation of the workflow then uses the contract. See [Associating workflows to contracts](https://docs.chainloop.dev/concepts/contracts.md#associating-workflows-to-contracts).

```bash theme={"dark"}
chainloop workflow contract create --name my-app-ci --contract my-app-ci.yaml
chainloop workflow create --name ci --project my-app --contract my-app-ci
```

Several workflows can use the same contract. For example, all your deploy workflows can share one CD contract. The [End-to-End Example](#end-to-end-example) shows the full contracts.

## Step 2: Instrument Each Stage to Send Attestations

Each stage of your pipeline sends its evidence to Chainloop with the [attestation lifecycle](https://docs.chainloop.dev/concepts/attestations.md#attestation-lifecycle) of the Chainloop CLI. Add these steps to the CI/CD job of the stage:

1. **Install the CLI.** See [Install the CLI](https://docs.chainloop.dev/cli/installation.md).
2. **Authenticate.** Set an [API token](https://docs.chainloop.dev/reference/api-tokens.md) in the `CHAINLOOP_TOKEN` environment variable. In GitHub Actions and GitLab CI, you can use [keyless attestation](https://docs.chainloop.dev/guides/github-keyless.md) with the OIDC token of the runner instead.
3. **Start the attestation** with `chainloop attestation init`. Give the workflow, the project, and the project version.
4. **Add the evidence** with `chainloop attestation add`, for example the container image, the SBOM, or the test results.
5. **Send the attestation** with `chainloop attestation push`. If the job fails before the push, run `chainloop attestation reset` to mark the workflow run as failed.

This GitHub Actions job attests the `ci` stage:

```yaml theme={"dark"}
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      CHAINLOOP_TOKEN: ${{ secrets.CHAINLOOP_TOKEN }}
    steps:
      - name: Install Chainloop
        run: curl -sfL https://dl.chainloop.dev/cli/install.sh | bash -s

      - name: Start the attestation
        run: chainloop attestation init --workflow ci --project my-app --version ${{ github.ref_name }}

      # Build and push the container image here

      - name: Add the evidence
        run: chainloop attestation add --name container --value ghcr.io/my-org/my-app:${{ github.ref_name }}

      - name: Send the attestation
        run: chainloop attestation push

      - name: Mark the workflow run as failed
        if: ${{ failure() }}
        run: chainloop attestation reset
```

[CI integration](https://docs.chainloop.dev/concepts/attestations.md#ci-integration) shows full examples for GitHub and GitLab.

> [!TIP]
>
> **Use a reusable template.** Put the attestation steps in one template, and call it from the pipeline of each stage. In GitHub, use a [reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows). In GitLab, use a [CI/CD component](https://docs.gitlab.com/ci/components/) or an [`include`](https://docs.gitlab.com/ci/yaml/includes/) file. The template gets the workflow, the project, the version, and the materials as inputs. Then each stage attests in the same way, and you change the steps in one place.

### Set the Same Project and Version in Every Stage

The project and the version that you give to `chainloop 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](https://docs.chainloop.dev/concepts/compliance-frameworks.md) 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 `--version` flag.** Give the same `--project` and `--version` to `chainloop attestation init` in every stage. Chainloop creates the version if it does not exist.

  ```bash theme={"dark"}
  chainloop attestation init --workflow ci --project my-app --version v1.4.0
  ```

* **A `.chainloop.yml` file.** Put the version in a `.chainloop.yml` file in the repository. The CLI reads it during `chainloop attestation init`, so the stages do not need the `--version` flag. See [Automatically load the version](https://docs.chainloop.dev/concepts/projects-versions.md#automatically-load-the-version).

  ```yaml theme={"dark"}
  projectVersion: v1.4.0
  ```

Both ways let your pipeline set the version, for example from a git tag or a build variable. A CD stage often runs in a different pipeline than the CI stage. Make sure that it gets the same version, for example from the tag of the image that it deploys.

## 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](https://docs.chainloop.dev/concepts/evidence-graph.md) explains how Chainloop connects the nodes.

You can link the stages in different ways:

| Mechanism | How it works | When to use it |
| - | - | - |
| Artifact (recommended) | Each stage adds the artifact, for example the container image, as a material. | The CD stage knows which artifact it deploys. This is the usual case. |
| `STRING` material | Each stage adds the same value, for example the CI build ID, as a `STRING` material. | The CD stage cannot get the artifact reference, but it can get an identifier from the CI run. |
| Git commit | The CLI records the git head commit automatically when it runs in a git repository. | Both stages run on a checkout of the same commit. A CD pipeline often does not check out the source, so do not rely on it alone. |
| Attestation digest | The CD stage adds the CI attestation as an `ATTESTATION` material. | Not recommended. The CD stage must find and download the CI attestation first. |

To link by artifact, add the image to the attestation in the CI stage and in the CD stage:

```bash theme={"dark"}
chainloop attestation add --name container --value ghcr.io/my-org/my-app:v1.4.0
```

To link by an identifier, add it as a `STRING` material in both stages:

```bash theme={"dark"}
chainloop attestation add --name build-id --value 20261117.3 --kind STRING
```

The `build-id` material does not need to be in the contracts. You can add it as a [contract-less material](https://docs.chainloop.dev/concepts/attestations.md#contract-less%2C-auto-discoverable-materials).

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.

> [!NOTE]
>
> **Remote state does not link stages.** [Remote state](https://docs.chainloop.dev/concepts/attestations.md#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 discover`](https://docs.chainloop.dev/cli/reference#chainloop-discover) with the digest of the artifact:

```bash theme={"dark"}
chainloop discover --digest sha256:8edec5932ca50412dfb50c5f55cbd4e31a735c19618749b909e2e8e311754c6a
```

Each entry in the output is an attestation that references the image. Its `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:

```json theme={"dark"}
{
  "digest": "sha256:f8d322eca1671fd68d7dcc4adb11a733789348a51fee3e2335870bb5cc8c4023",
  "kind": "ATTESTATION",
  "metadata": {
    "name": "ci",
    "project": "my-app",
    "projectVersion": "v1.4.0",
    "contractName": "my-app-ci",
    "hasPolicyViolations": "false",
    "hasGatedPolicyViolations": "false"
  }
}
```

This graph is the base for the control gates in the next step. You can also read it with the API and in policies. See [Query the Graph](https://docs.chainloop.dev/concepts/evidence-graph.md#query-the-graph).

## Step 5: Add a Control Gate Before Deployment

A control gate is a policy with `gate: 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](https://docs.chainloop.dev/concepts/control-gates.md).

Chainloop gives you four types of checks for a CD stage:

| Check | Question it answers | How |
| - | - | - |
| Upstream workflow | Did the CI workflow attest this artifact with no policy violations? | Built-in [`upstream-check`](https://docs.chainloop.dev/reference/policies#upstream-check) policy |
| Required evidence | Does the project version contain the evidence I need, for example an SBOM? | Custom policy with [`chainloop.evidence`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-evidence) and [`chainloop.discover`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-discover). See [Example 2](https://docs.chainloop.dev/concepts/control-gates.md#example-2-check-required-pieces-of-evidence). |
| Evidence content | Does the upstream evidence pass my rules, for example a minimum test pass rate or coverage? | Custom policy that finds the evidence with [`chainloop.evidence`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-evidence) or [`chainloop.discover`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-discover), then reads it with [`chainloop.download_artifact`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-download-artifact). |
| Compliance requirement | Does the project version meet its compliance requirements? | Built-in [`check-compliance-requirement`](https://docs.chainloop.dev/reference/policies#check-compliance-requirement) policy. See [Example 1](https://docs.chainloop.dev/concepts/control-gates.md#example-1-check-compliance-requirements-for-my-project). For custom logic, use [`chainloop.project_compliance`](https://docs.chainloop.dev/reference/builtin-functions#chainloop-project-compliance) in a custom policy. |

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: all` checks 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-violations` fails 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 the `latest` tag.

```yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: my-app-ci
spec:
  materials:
    - name: container
      type: CONTAINER_IMAGE
  policies:
    materials:
      - ref: artifact-tag-not-latest
      - ref: artifact-signed
```

Create the contract and the `ci` workflow:

```bash theme={"dark"}
chainloop workflow contract create --name my-app-ci --contract my-app-ci.yaml
chainloop workflow create --name ci --project my-app --contract my-app-ci
```

In the CI pipeline, after you build and push the image, attest it:

```bash theme={"dark"}
chainloop attestation init --workflow ci --project my-app --version v1.4.0
chainloop attestation add --name container --value ghcr.io/my-org/my-app:v1.4.0
chainloop attestation push
```

The example uses the same value for the image tag and the project version. This is a convention, not a requirement.

### CD Stage

The CD contract also requires the container image. The `upstream-check` policy checks that the latest `ci` run that attested this image has no policy violations. `gate: true` makes the policy a control gate.

```yaml theme={"dark"}
apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: my-app-cd
spec:
  materials:
    - name: container
      type: CONTAINER_IMAGE
  policies:
    materials:
      - ref: upstream-check
        with:
          workflow: ci # the upstream workflow that must attest the image
        selector:
          name: container
        gate: true
```

Create the contract and the two deploy workflows, which share it:

```bash theme={"dark"}
chainloop workflow contract create --name my-app-cd --contract my-app-cd.yaml
chainloop workflow create --name deploy-staging --project my-app --contract my-app-cd
chainloop workflow create --name deploy-production --project my-app --contract my-app-cd
```

In the CD pipeline, attest the image before you deploy it:

```bash theme={"dark"}
chainloop attestation init --workflow deploy-staging --project my-app --version v1.4.0
chainloop attestation add --name container --value ghcr.io/my-org/my-app:v1.4.0
chainloop attestation push
```

When the CI stage attested the image with no violations, the push output shows that the check passed:

```
┌──────────┬──────────────────────────────────────────────────────────────────────────┐
│ Name     │ container                                                                │
│ Type     │ CONTAINER_IMAGE                                                          │
│ Value    │ ghcr.io/my-org/my-app:v1.4.0                                             │
│ Digest   │ sha256:8edec5932ca50412dfb50c5f55cbd4e31a735c19618749b909e2e8e311754c6a  │
│ Policies │ upstream-check: Ok                                                       │
└──────────┴──────────────────────────────────────────────────────────────────────────┘
```

The push fails when the CI stage did not attest the image, or when its run has policy violations. The pipeline then stops before the deployment step.

## 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 example `deploy-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](https://docs.chainloop.dev/concepts/deployments.md).

## 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](https://docs.chainloop.dev/concepts/contracts.md#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](https://docs.chainloop.dev/concepts/workflow-templates.md) bundle a contract and its inputs into a reusable blueprint, so each team creates its workflows from the same definition.

## Next Steps

* [Control Gates](https://docs.chainloop.dev/concepts/control-gates.md): turn on enforcement and record bypasses
* [Built-in policies](https://docs.chainloop.dev/reference/policies.md): all the policies that you can attach to a contract
* [Custom policies](https://docs.chainloop.dev/guides/custom-policies.md): write your own gate with the built-in functions
* [Projects and Versions](https://docs.chainloop.dev/concepts/projects-versions.md): manage the versions that your stages attest to


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.