Lab 4: Release Controls

Define compliance requirements with Flow Templates and gate deployments with kosli assert artifact.

Prerequisites: Complete Lab 3: Build Controls before starting this lab.

Learning goals

• Understand Flow Templates and how they define compliance requirements
• Update an existing Flow to enforce specific attestations
• Understand the difference between compliant and non-compliant Trails
• Use kosli assert artifact to gate deployments based on compliance status

Introduction

In the previous labs, you’ve been recording evidence (attestations) for your builds. However, recording evidence is only half the picture — you also need to ensure the required evidence is actually present before allowing a release.

Flow Templates define the “shape” of a compliant release. They specify:

• Which artifacts are expected in the Trail
• Which attestations are required for each artifact
• Which attestations are required at the Trail level

When a Trail is evaluated against its Flow Template, Kosli determines if it is Compliant or Non-compliant. By adding kosli assert artifact to your pipeline, you can automatically block deployments that don’t meet your compliance standards.

See Flow Templates for the full template specification.

Exercise

1. Define compliance requirements

   Create a file named flow-template.yaml in the root of your repository:

   # yaml-language-server: $schema=https://kosli.mintlify.app/schemas/flow-template.json
   version: 1
   trail:
     artifacts:
       - name: application
         attestations:
           - name: unit-tests
             type: junit
       - name: docker-image
         attestations:
           - name: sbom
             type: generic
   

   This template matches the attestations you set up in Lab 3:

   1. An application artifact that must have unit-tests
   2. A docker-image artifact that must have an sbom
2. Update the Flow to use the template

   In .github/workflows/full-pipeline.yaml, find the Create/Update Flow step (added in Lab 2) and replace --use-empty-template with --template-file:

         - name: Create/Update Flow
           run: |
             kosli create flow ${APP_NAME}-pipeline \
               --description "CI/CD pipeline for ${APP_NAME} application" \
               --template-file flow-template.yaml
   
3. Gate the release

   In the Deploy job, add the following steps before the “Deploy to production” step:

       - name: Setup Kosli CLI
         uses: kosli-dev/setup-cli-action@v2
         with:
           version: 2.11.32
   
       - name: Assert compliance
         run: |
           IMAGE_NAME="ghcr.io/${IMAGE}:latest"
           kosli assert artifact ${IMAGE_NAME} \
             --artifact-type oci \
             --flow ${APP_NAME}-pipeline
   

   This command asks Kosli: “Is this artifact and its Trail compliant?”

   • Compliant (all required attestations present and none failing): exits 0 — pipeline continues to deploy
   • Non-compliant (missing or failing attestations): exits 1 — pipeline fails, deployment is blocked

   See kosli assert artifact for full flag reference.

4. Push and test the gate

   git add flow-template.yaml .github/workflows/full-pipeline.yaml
   git commit -m "Add Flow Template and Release Gate"
   git push origin main
   

   Watch the workflow run. Since you’re providing all required attestations from Lab 3, the Assert compliance step should pass (green).

   Then in app.kosli.com, navigate to your Flow → latest Trail. The Compliance status should show Compliant with all template requirements checked off.

Optional: test non-compliance

To see the gate in action, add a non-existent attestation requirement to flow-template.yaml:

    - name: docker-image
      attestations:
        - name: sbom
          type: generic
        - name: performance-test  # We haven't implemented this yet!
          type: generic

Commit and push. The Assert compliance step should fail, preventing the deploy step from running. The Trail in Kosli will be marked Non-compliant.

Remember to revert this change to make your pipeline green again.

Verification checklist

• flow-template.yaml created in repository root
• Workflow updated to apply the template
• kosli assert artifact added to the Deploy job
• A fully attested build passes the compliance gate
• Trail shows as Compliant in the Kosli web interface

If anything didn’t go to plan, refer to the reference solution at pipelines/04-complete.yaml in the labs repository.

Next steps

Continue to Lab 5: Runtime Controls to track what’s running in production and enforce compliance policies.

Further reading:

• Flows
• Flow Template reference