Adding trail summaries to CI pipeline runs

kosli get trail --output markdown renders a trail as GitHub-Flavored Markdown — compliance state, git commit, attestation statuses, and events, with links back to the Kosli app. Pipe it into your CI’s job summary and every pipeline run becomes an information radiator for the trail it produced. By the end of this tutorial, you will have added a Kosli trail summary to a GitHub Actions job summary and to a GitLab CI pipeline.

Prerequisites

Install Kosli CLI on your CI runner (e.g. via kosli-dev/setup-cli-action on GitHub).
A flow and trail you are already reporting to during the pipeline. See Querying Kosli if you need to find the flow and trail name.
KOSLI_API_TOKEN and KOSLI_ORG available to the job (see Authenticating to Kosli).

What the markdown output looks like

Run the command locally first to see what will end up in your CI summary:

kosli get trail my-trail-name --flow my-flow --output markdown

The output is a markdown document with:

A ## Trail: <name> heading linked to the trail page in the Kosli app.
A metadata table (name, description, compliance, last modified, origin).
A ### Git commit table with the commit author, timestamp, and subject.
An ### Attestations section with one headerless table per artifact (and one for trail-level attestations), with each attestation linked to its place on the trail page. Statuses are prefixed with ✅ / ❌ / ⏳; attestations reported but not expected by the template are marked with (+).
An ### Events table with timestamps, descriptions, commit links, and compliance state.

Trail summary showing compliance status, git commit metadata, per-artifact attestation tables, and event history

Publishing the summary

GitHub
GitLab

GitHub Actions exposes a per-job markdown summary via the $GITHUB_STEP_SUMMARY environment variable. Anything you append to that file is rendered on the workflow run page.Add a final step to your job that writes the trail summary to it:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      KOSLI_API_TOKEN: ${{ secrets.KOSLI_API_TOKEN }}
      KOSLI_ORG: my-org
      KOSLI_FLOW: my-flow
      KOSLI_TRAIL: ${{ github.sha }}
    steps:
      - uses: actions/checkout@v7

      - name: Setup Kosli CLI
        uses: kosli-dev/setup-cli-action@v5

      # ... your build, attest, and report steps ...

      - name: Publish Kosli trail summary
        if: always()
        run: |
          kosli get trail "$KOSLI_TRAIL" \
            --flow "$KOSLI_FLOW" \
            --output markdown >> "$GITHUB_STEP_SUMMARY"

if: always() makes sure the summary is published even when an earlier step fails — that is when you most want to see which attestation is missing or non-compliant.The summary appears on the run’s page under the job, with the trail name linking back to the trail in the Kosli app and every attestation linking to its position on the trail.

GitLab does not natively render markdown inline on the job page, but artifacts:expose_as surfaces the summary.md artifact as a labeled link in the merge request widget, one click away from the rendered file in the GitLab UI.Add a job (or a final step in your existing job) that produces that artifact. Use the Kosli Alpine CI runner image so kosli, git, and curl are preinstalled and no before_script setup is needed:

kosli-trail-summary:
  stage: .post
  image: registry.example.com/ci/kosli-runner:2.28.0  # replace with the tag you pushed
  variables:
    KOSLI_FLOW: my-flow
    KOSLI_TRAIL: $CI_COMMIT_SHA
  script:
    - >
      kosli get trail "$KOSLI_TRAIL"
      --flow "$KOSLI_FLOW"
      --output markdown > summary.md
  artifacts:
    when: always
    paths:
      - summary.md
    expose_as: "Kosli trail summary"

Replace registry.example.com/ci/kosli-runner:2.28.0 with whatever tag you pushed when you built the Alpine image — see CI runner image (Alpine) for the build steps.KOSLI_API_TOKEN and KOSLI_ORG should be set as CI/CD variables on the project or group, masked, so the job picks them up automatically.when: always mirrors the GitHub if: always() pattern: the summary is uploaded even if earlier stages fail.

Tips

Pin a specific trail by exporting KOSLI_TRAIL early in the pipeline (commonly to the commit SHA you used in kosli begin trail). Every later step — including the summary — then targets the same trail.
The markdown output is stable text. You can also commit it as a build artifact or attach it to a release for an audit-friendly record of what was reported for that build.
Run kosli get trail --output markdown locally against a real trail before wiring it into CI. It is the fastest way to see what your team will see on the pipeline page.

What you’ve accomplished

You have published a live Kosli trail summary — compliance state, attestations, and events — directly onto your GitHub Actions and GitLab CI pipeline pages, turning every build into a feedback channel for the trail it produced. From here you can:

Read the full kosli get trail reference.
Browse other CI/CD integration patterns.

​Prerequisites

​What the markdown output looks like

​Publishing the summary

​Tips

​What you’ve accomplished

Prerequisites

What the markdown output looks like

Publishing the summary

Tips

What you’ve accomplished