Workflow Templates

Overview

Preview. Workflow templates are available on Chainloop’s paid plans and are currently a Preview feature — the schema and behavior may change.

A Workflow Template is a reusable blueprint for creating workflows. Instead of configuring a contract and delivery settings from scratch for every project, you define a template once and instantiate it wherever you need it — while onboarding a project, editing an existing one, or adding a new workflow. A template bundles together everything a workflow needs:

A contract — either embedded inline or a reference to an existing organization contract — that defines the evidence and policies the resulting workflow expects.
Delivery mode(s) — how attestations reach Chainloop.
Inputs (optional) — parameters that let a single template adapt to different projects.

Templates come in two flavors:

Built-in templates — global, Chainloop-provided blueprints (for example, vulnerability, SAST, and secret scans) available to every organization.
Custom templates — org-scoped blueprints you define and manage yourself with chainloop apply.

Anatomy of a Template

Workflow templates follow the same Kubernetes-style schema as other declarative resources, with apiVersion, kind, metadata, and spec:

apiVersion: chainloop.dev/v1
kind: WorkflowTemplate
metadata:
  name: vulnerability-scan
  display_name: Vulnerability Scan
  description: >-
    Validates dependency / artifact vulnerability reports against the vulnerability-management
    policy group and verifies the commit that triggered the scan.
spec:
  delivery:
    - DELIVERY_MODE_MANUAL
  contract:
    materials:
      - type: SARIF
        name: vulnerability-report
      - type: SBOM_CYCLONEDX_JSON
        name: sbom
    policies:
      attestation:
        - ref: source-commit
      materials:
        - ref: cves-in-kev
    policy_groups:
      - ref: vulnerability-management

Metadata

Name	Required	Description
`name`	yes	Machine-readable, globally unique identifier (lowercase letters, numbers, and hyphens — DNS-1123).
`display_name`	no	Human-readable name shown in the UI.
`description`	no	Short summary of what the template does, shown alongside it in the UI.

Spec

Name	Required	Description
`delivery`	no	List of supported delivery modes. Defaults to manual delivery when omitted.
`contract`	*	An embedded contract (`materials`, `policies`, `policy_groups`). Mutually exclusive with `contract_ref`.
`contract_ref`	*	Name of an existing organization contract to reference instead of embedding one. Mutually exclusive with `contract`.
`inputs`	no	Configurable inputs the template advertises. Only valid with an embedded `contract`, not with `contract_ref`.
`singleton`	no	If `true`, only one workflow instance per repository can be created from this template.
`scmProviders`	no	Restrict which repositories can use the template by SCM provider (`GITHUB`, `GITLAB`). Empty means all providers.
`manual_installation_description`	no	Markdown instructions shown for manual/self-service setup.

Exactly one of contract or contract_ref must be set — never both, and never neither.

Embedded vs. Referenced Contracts

A template can carry its contract in one of two ways:

Embedded — define the contract inline under spec.contract. Use this when the contract is specific to the template.
Referenced — point at an existing organization contract by name with spec.contract_ref. Use this when you want several templates to share (and stay in sync with) a single contract.

spec:
  delivery:
    - DELIVERY_MODE_MANUAL
  contract_ref: my-org-contract

Delivery Modes

spec.delivery declares how workflows created from the template deliver their attestations.

DELIVERY_MODE_MANUAL — the push model: attestations are performed from your own CI/CD pipeline and pushed to Chainloop. This is the mode you use in your own templates. When delivery is omitted, the template defaults to manual delivery.
DELIVERY_MODE_MANAGED — reserved for Chainloop’s own system and used by built-in templates. It is not intended for custom templates.

Template Inputs

Templates can declare inputs — parameters that make a single template reusable across projects with different requirements. Inputs are referenced as {{ inputs.<name> }} placeholders inside policy and policy group parameters, so a shared template can ship policies that need organization- or project-specific values.

apiVersion: chainloop.dev/v1
kind: WorkflowTemplate
metadata:
  name: vulnerability-scan
  display_name: Vulnerability Scan
spec:
  delivery:
    - DELIVERY_MODE_MANUAL
  inputs:
    - name: severity
      description: Minimum severity that fixes are expected to address within the defined SLA.
      type: string
      default: "HIGH"
  contract:
    materials:
      - type: SARIF
        name: vulnerability-report
    policy_groups:
      - ref: vulnerability-management
        with:
          severity: "{{ inputs.severity }}"

Each input supports the following fields:

Name	Required	Description
`name`	yes	Identifier used in `{{ inputs.<name> }}` placeholders (letters, numbers, and underscores; must start with a letter).
`description`	no	Human-readable description shown in the UI.
`type`	no	Scalar type of the input. Currently only `string` is supported.
`enum`	no	Optional list of allowed values.
`default`	no	Default value used when none is provided.
`required`	no	Whether a value must be supplied.

Input values are validated when the template is applied and can be edited later from the project and workflow edit forms.

Managing Custom Templates

Custom (org-scoped) templates are managed declaratively with chainloop apply, the same command used for other Chainloop resources. Applying a template creates it if it does not exist, or updates it if a template with the same name already exists:

# Apply a single template
chainloop apply -f vulnerability-scan.yaml

# Apply every template in a directory
chainloop apply -f ./workflow-templates/

Use --dry-run to validate a template and preview the changes without persisting them:

chainloop apply -f vulnerability-scan.yaml --dry-run

Creating and updating org-scoped workflow templates requires an admin or owner role. Built-in templates are read-only.

Using Templates

Templates show up across the UI. You can:

Create a workflow from a template — pick a template and Chainloop provisions a workflow with the template’s contract, delivery mode, and input values already wired up.
Select templates while onboarding or editing a project — attach one or more templates as part of project setup.

For example, the Workflows step of the Create Project wizard lists the built-in and custom templates available for the project’s repository, letting you enable each one and choose its delivery mode inline:

The Workflows step of the Create Project wizard showing built-in workflow templates such as GitHub Actions Scan, IaC Scan, PR Validation, and SAST Scan, each with a delivery mode selector and a Configure option

Each workflow remembers the template it was created from, so template-backed workflows can be recognized and updated consistently.

Getting Started

Concepts

Guides

References

Misc

Overview

Anatomy of a Template

Metadata

Spec

Embedded vs. Referenced Contracts

Delivery Modes

Template Inputs

Managing Custom Templates

Using Templates

​Overview

​Anatomy of a Template

​Metadata

​Spec

​Embedded vs. Referenced Contracts

​Delivery Modes

​Template Inputs

​Managing Custom Templates

​Using Templates

Overview

Anatomy of a Template

Metadata

Spec

Embedded vs. Referenced Contracts

Delivery Modes

Template Inputs

Managing Custom Templates

Using Templates