Flow Template

Reference for the YAML template file used to define compliance controls for a Kosli flow.

A flow template defines what attestations are required for a trail and its artifacts to be compliant. You pass the template file when creating or updating a flow with kosli create flow --template-file.

Specification

version · integer · required

The version of the specification schema. Currently only 1 is supported.

trail · object

The trail specification. Defines what must be attested at the trail level and what artifacts are expected.

Show trail properties

trail.attestations · array

Attestations required at the trail level for it to be compliant.

Show attestation properties

trail.attestations[].name · string · required

A unique name for the attestation within this template.

trail.attestations[].type · string · required

The attestation type. One of: generic, jira, junit, pull_request, snyk, sonar, * (matches any type).

trail.artifacts · array

Artifacts expected to be produced in the trail. Each artifact can have its own attestation requirements.

Show artifact properties

trail.artifacts[].name · string · required

A reference name for the artifact (e.g. frontend-app, backend).

trail.artifacts[].attestations · array

Attestations required for this artifact to be compliant.

Show attestation properties

trail.artifacts[].attestations[].name · string · required

A unique name for the attestation within this artifact.

trail.artifacts[].attestations[].type · string · required

The attestation type. One of: generic, jira, junit, pull_request, snyk, sonar, or custom:<custom-type-name> for custom attestation types.

Example

Add the $schema comment to get editor validation and autocomplete:

# yaml-language-server: $schema=https://kosli.mintlify.app/schemas/flow-template.json
version: 1
trail:
  attestations:
  - name: jira-ticket
    type: jira
  - name: risk-level-assessment
    type: generic
  artifacts:
  - name: backend
    attestations:
    - name: unit-tests
      type: junit
    - name: security-scan
      type: snyk
  - name: frontend
    attestations:
    - name: manual-ui-test
      type: generic
    - name: coverage-metrics
      type: custom:coverage-metrics

Using the template

Pass the template file when creating or updating a flow:

kosli create flow my-flow --template-file ./flow-template.yml

Once the flow exists, start a trail with kosli begin trail and record attestations using the kosli attest commands. Kosli evaluates trail compliance against the template automatically.

Trail-level attestations apply to the entire trail. Artifact-level attestations apply to a specific artifact produced within the trail.

Editor validation

A JSON Schema is available for the flow template format. Add the following comment to the top of your template file to enable inline validation and autocomplete in VS Code (requires the YAML extension) and other schema-aware editors:

# yaml-language-server: $schema=https://kosli.mintlify.app/schemas/flow-template.json