info A Chainloop contract becomes the interface between the developers who must instrument their CI/CD pipelines and Security and Compliance teams. A Workflow Contract defines the expectations of what content a workflow must send as part of their attestation. For example, a contract could explicitly state that the URI@digest of the generated container image, the container rootfs used during build, and the Software Bill of Materials of that container image must be present in the attestation. There are two additional properties of Workflow Contracts that aims to ease the management of workflows in your organization
  • A Workflow Contract is immutable and versioned, new revisions of the contract with new/different requirements can be added over time. This is especially useful for iterative integrations.
  • A Workflow Contract can belong to more than one Workflow. This means that a change in a single contract will be propagated to many workflows. This is especially useful for org-wide standardization and fleet management.
Example: three CI/CD pipelines associated with their respective Chainloop workflows. Two of those Workflows are sharing the same Contract (using the same or different revision). info

​
Managing Contracts

Contracts can be managed through the “Contracts” section in Chainloop platform:info
There is always a default, empty contract to speed up organization onboarding. A new contract can be added by clicking “Create Contract” form, where you can specify the name, description, and contract specification:
info
A Workflow Contract can be provided in json or yaml (cue format is also supported through the Chainloop CLI).

​
Contract Management Scope

Contracts in Chainloop operate at two different scopes with corresponding management permissions:
  • Organization-scope contracts: Managed by users with Organization Admin or Organization Owner roles. These contracts can be used across all projects within the organization.
  • Project-scope contracts: Managed by Project Admins. These contracts are specific to individual projects and can only be used within their respective project scope.
For detailed information about roles and permissions, see our RBAC documentation.

​
Associating workflows to contracts

Once contracts are created, they can be attached to as many workflows as needed. Remember that workflows represent a unique source of data ingestion (attestations), usually representing a CI/CD pipeline.
In the workflow view, click on the edit icon and associate the contract. Once the contract is associated, new attestations will automatically download and apply it, including required materials, policies, and so on.info

​
Writing contracts

​
Example

See below a contract schema example:
Note that the contract below is just an example crafted for educational purposes. In a real scenario, the contract will not contain such a despaired amount of materials or annotations.
schemaVersion: v1
# Arbitrary set of annotations can be added to the contract and will be part of the attestation
annotations:
  - name: version
    value: oss # if the value is left empty, it will be required and resolved at attestation time

# https://docs.chainloop.dev/concepts/operator/material-types
materials:
  # CONTAINER_IMAGE kinds will get resolved to retrieve their repository digest
  - type: CONTAINER_IMAGE
    name:
      skynet-control-plane
      # The output flag indicates that the material will be part of the attestation subject
    output: true
    # Arbitrary annotations can be added to the material
    annotations:
      - name: component
        value: control-plane
      # The value can be left empty so it can be provided at attestation time
      - name: asset
  # ARTIFACT kinds will first get uploaded to your artifact registry via the built-in Content Addressable Storage (CAS)
  # Optional dockerfile
  - type: ARTIFACT
    name: dockerfile
    optional: true
  # SBOMs will be uploaded to the artifact registry and referenced in the attestation
  # Both SBOM_CYCLONEDX_JSON and SBOM_SPDX_JSON are supported
  - type: SBOM_CYCLONEDX_JSON
    name: skynet-sbom
  # CSAF_VEX and OPENVEX are supported
  - type: OPENVEX
    name: disclosure
  # And static analysis reports in SARIF format
  - type: SARIF
    name: static-out
  # or additional tools
  - type: TWISTCLI_SCAN_JSON
    name: scan-result

# https://docs.chainloop.dev/concepts/policies
policies:
  materials: # policies applied to materials
    - ref: file://cyclonedx-licenses.yaml 
  attestation: # policies applied to the whole attestation
    - ref: https://github.com/chainloop/chainloop-dev/blob/main/docs/examples/policies/chainloop-commit.yaml # (2)

# Env vars we want the system to resolve and inject during attestation initialization
# Additional ones can be inherited from the specified runner context below
envAllowList:
  - CUSTOM_VAR

# Enforce in what runner context the attestation must happen
# If not specified, the attestation crafting process is allowed to run anywhere
runner:
  type: "GITHUB_ACTION"
Once they are created, contracts can be edited. Every change will be stored as a new version of the contract. Chainloop CLI will automatically retrieve the latest version of the contract when a new attestation is performed. The contract summary view will provide details about the contract: info

​
Schema

NameRequiredDescription
schemaVersionyesVersion of the schema, it needs to be v1
materialsnoList of materials to be added to the attestation
envAllowListnoList of environment variables that will be resolved and injected in the attestation
runnernoSpecific runner type associated with this contract. If not set, this contract will be valid to be run anywhere but you’ll miss out some of its benefits
annotationsnoName/Value pairs of arbitrary annotations that will be added to the attestation. If the value is not provided, it will be required during the attestation process.
policiesnoAttachments to existing Chainloop policies. See policies reference guide for more information

​
Materials

The contract can require one or more pieces of evidence (a.k.a material) to be attached during the attestation process.
NameRequiredDefaultDescription
nameyesunique identifier of the material
typeyesRefer to material-types for the list of supported material types.
outputnofalseIf set to true the material will get injected in the subject section of the in-toto statement.
optionalnofalseif set to true, providing this material during attestation will be optional. This is useful for soft rollouts of new requirements
annotationsnoName/Value pairs of arbitrary annotations that will be added to the attestation. If the value is not provided, it will be required during the attestation process.

​
Policy attachments

When defining a contract, a new policies section can be specified. Policies can be applied to any material, but also to the attestation statement as a whole. 
schemaVersion: v1
materials:
  - name: sbom
    type: SBOM_CYCLONEDX_JSON
  - name: another-sbom
    type: SBOM_CYCLONEDX_JSON
  - name: my-image
    type: CONTAINER_IMAGE
policies:
  materials: # policies applied to materials
    - ref: file://cyclonedx-licenses.yaml # (1)
  attestation: # policies applied to the whole attestation
    - ref: https://github.com/chainloop/chainloop-dev/blob/main/docs/examples/policies/chainloop-commit.yaml # (2)
Read the docs for full details on policies.

​
Runner Context

New runner contexts will be added over time. If yours is not implemented yet, please contact us
An optional runner type can be provided in a workflow contract.
skynet.contract.yaml showLineNumbers
schemaVersion: v1
materials:
  - type: CONTAINER_IMAGE
    name: skynet-control-plane
envAllowList:
  - CUSTOM_VAR
# highlight-start
runner:
  type: "GITHUB_ACTION"
# highlight-end
It has the following effect on the attestation process.
  • Require the attestation process to be executed in the target runner type unless the --dry-run flag is set during initialization.
  • A link to the workload (i.e Github Action Run link) will be recorded both in the attestation and in the control plane during initialization.
  • An additional set of environment variables will be resolved in addition to the ones defined in the contract envAllowList.
Currently, we support the following runner types

​
AZURE_PIPELINE

The following environment variables will be automatically added to the attestation. For more information on what they mean, refer to this link.
  • BUILD_REQUESTEDFOREMAIL
  • BUILD_REQUESTEDFOR
  • BUILD_REPOSITORY_URI
  • BUILD_REPOSITORY_NAME
  • BUILD_BUILDID
  • BUILD_BUILDNUMBER
  • BUILD_BUILDURI
  • BUILD_REASON
  • AGENT_VERSION
  • TF_BUILD
A link to the Azure Pipeline build will be recorded in the control plane too during initialization.

​
CIRCLECI_BUILD

The following environment variables will be automatically added to the attestation. For more information on their meaning, refer to the official CircleCI documentation.
  • CIRCLE_BUILD_URL
  • CIRCLE_JOB
  • CIRCLE_BRANCH (optional)
  • CIRCLE_NODE_TOTAL
  • CIRCLE_NODE_INDEX
A link to the CircleCI build will be recorded in the control plane too, during initialization.

​
DAGGER_PIPELINE

To use Chainloop With Dagger you can use this Dagger module

​
GITHUB_ACTION

The following environment variables will be automatically added to the attestation. For more information on what they do refer to this link.
  • GITHUB_ACTOR
  • GITHUB_REF
  • GITHUB_REPOSITORY
  • GITHUB_REPOSITORY_OWNER
  • GITHUB_RUN_ID
  • GITHUB_SHA
  • RUNNER_NAME
  • RUNNER_OS
A link to the Github Action will be recorded in the control plane too during initialization.

​
GITLAB_PIPELINE

The following environment variables will be automatically added to the attestation. More information about what they mean in GitLab’s official documentation
  • GITLAB_USER_EMAIL
  • GITLAB_USER_LOGIN
  • CI_PROJECT_URL
  • CI_COMMIT_SHA
  • CI_JOB_URL
  • CI_PIPELINE_URL
  • CI_RUNNER_VERSION
  • CI_RUNNER_DESCRIPTION
  • CI_COMMIT_REF_NAME
A link to the GitLab CI job will be recorded in the control plane too, during initialization.

​
JENKINS_JOB

The following environment variables will be automatically added to the attestation. For more information on how to use Jenkins environment variables, refer to the official Jenkins documentation.
  • JOB_NAME
  • BUILD_URL
  • GIT_BRANCH (optional)
  • GIT_COMMIT (optional)
  • AGENT_WORKDIR
  • NODE_NAME
A link to the build will be recorded in the control plane too, during initialization.

​
TEAMCITY_PIPELINE

The following environment variables will be automatically added to the attestation. For more information on TeamCity environment variables, refer to the official TeamCity documentation.
  • BUILD_URL
  • TEAMCITY_PROJECT_NAME
  • TEAMCITY_VERSION
  • BUILD_NUMBER
  • USER
  • TEAMCITY_GIT_VERSION
  • BUILD_VCS_NUMBER
  • HOME
A link to the TeamCity build will be recorded in the control plane too, during initialization.
Remember, if all the env variables that you need are not defined in the context, you can extend such list via the envAllowList option.