docs: add tutorial for publishing trail summaries to GitHub and GitLab CI

config/navigation.json

@@ -107,7 +107,8 @@
               "pages": [
                 "tutorials/querying_kosli",
                 "tutorials/following_a_git_commit_to_runtime_environments",
-                "tutorials/tracing_a_production_incident_back_to_git_commits"
+                "tutorials/tracing_a_production_incident_back_to_git_commits",
+                "tutorials/trail_summaries_in_ci"
               ]
             },
             {

integrations/ci_cd.md

@@ -59,7 +59,7 @@ description: Use Kosli in CI Systems like GitHub Actions, GitLab CI, and more.
         KOSLI_ORG: my-org
       steps:
         - name: setup kosli
-          uses: kosli-dev/setup-cli-action@v2
+          uses: kosli-dev/setup-cli-action@v5
         - name: create flow
           run: kosli create flow my-flow --template pull-request,artifact,test
   ```
@@ -95,10 +95,10 @@ description: Use Kosli in CI Systems like GitHub Actions, GitLab CI, and more.
   ```bash
   # Clone or copy Dockerfile.alpine from https://github.com/kosli-dev/cli
   docker build \
-    --build-arg KOSLI_VERSION=2.13.2 \
+    --build-arg KOSLI_VERSION=2.28.0 \
     -f Dockerfile.alpine \
-    -t registry.example.com/ci/kosli-runner:2.13.2 .
-  docker push registry.example.com/ci/kosli-runner:2.13.2
+    -t registry.example.com/ci/kosli-runner:2.28.0 .
+  docker push registry.example.com/ci/kosli-runner:2.28.0
   ```
 
   Then use it as the job image in `.gitlab-ci.yml`:
@@ -109,7 +109,7 @@ description: Use Kosli in CI Systems like GitHub Actions, GitLab CI, and more.
     KOSLI_HOST: https://app.kosli.com
 
   attest:
-    image: registry.example.com/ci/kosli-runner:2.13.2
+    image: registry.example.com/ci/kosli-runner:2.28.0
     script:
       - kosli version
       - kosli attest generic

labs/lab-02-flows-and-trails.mdx

@@ -136,12 +136,12 @@ Think of a Flow as the template for your process, and Trails as individual insta
 
     ```yaml
           - name: Clone down repository
-            uses: actions/checkout@v4
+            uses: actions/checkout@v7
 
           - name: Setup Kosli CLI
-            uses: kosli-dev/setup-cli-action@v2
+            uses: kosli-dev/setup-cli-action@v5
             with:
-              version: 2.11.32
+              version: 2.28.0
 
           - name: Create/Update Flow
             run: |

labs/lab-03-build-controls.mdx

@@ -88,9 +88,9 @@ Kosli identifies artifacts by their **SHA256 fingerprint**. This uniquely identi
 
     ```yaml
         - name: Setup Kosli CLI
-          uses: kosli-dev/setup-cli-action@v2
+          uses: kosli-dev/setup-cli-action@v5
           with:
-            version: 2.11.32
+            version: 2.28.0
 
         - name: Attest Docker image
           run: |

labs/lab-04-release-controls.mdx

@@ -72,9 +72,9 @@ See [Flow Templates](/template-reference/flow_template) for the full template sp
 
     ```yaml
         - name: Setup Kosli CLI
-          uses: kosli-dev/setup-cli-action@v2
+          uses: kosli-dev/setup-cli-action@v5
           with:
-            version: 2.11.32
+            version: 2.28.0
 
         - name: Assert compliance
           run: |

tutorials/linking_trails_across_branches.md

@@ -173,7 +173,7 @@ Below is a simplified GitHub Actions workflow for a main-branch build that links
       build:
         runs-on: ubuntu-latest
         steps:
-          - uses: actions/checkout@v4
+          - uses: actions/checkout@v7
             with:
               fetch-depth: 2
 
@@ -226,7 +226,7 @@ Below is a simplified GitHub Actions workflow for a main-branch build that links
       build:
         runs-on: ubuntu-latest
         steps:
-          - uses: actions/checkout@v4
+          - uses: actions/checkout@v7
             with:
               fetch-depth: 2
 

tutorials/report_k8s_envs.md

@@ -98,7 +98,7 @@ jobs:
 
     steps:
       - name: Install Kosli CLI
-        uses: kosli-dev/setup-cli-action@v2
+        uses: kosli-dev/setup-cli-action@v5
 
       # Replace this step with one that connects to your cluster if not using GKE
       - name: Connect to GKE

tutorials/trail_summaries_in_ci.md

@@ -0,0 +1,118 @@
+---
+title: "Adding trail summaries to CI pipeline runs"
+description: "Use kosli get trail --output markdown to publish a Kosli trail summary directly to GitHub Actions and GitLab 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](/getting_started/install) on your CI runner (e.g. via [`kosli-dev/setup-cli-action`](https://github.com/marketplace/actions/setup-kosli-cli) on GitHub).
+* A flow and trail you are already reporting to during the pipeline. See [Querying Kosli](/tutorials/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](/getting_started/authenticating_to_kosli)).
+
+## What the markdown output looks like
+
+Run the command locally first to see what will end up in your CI summary:
+
+```shell
+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.
+
+## Publishing the summary
+
+<Tabs>
+  <Tab title="GitHub" icon="github">
+
+GitHub Actions exposes a per-job markdown summary via the [`$GITHUB_STEP_SUMMARY`](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-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:
+
+```yaml
+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.
+
+  </Tab>
+  <Tab title="GitLab" icon="gitlab">
+
+GitLab does not natively render markdown inline on the job page, but [`artifacts:expose_as`](https://docs.gitlab.com/ci/yaml/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](/integrations/ci_cd#ci-runner-image-alpine) so `kosli`, `git`, and `curl` are preinstalled and no `before_script` setup is needed:
+
+```yaml
+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)](/integrations/ci_cd#ci-runner-image-alpine) for the build steps.
+
+`KOSLI_API_TOKEN` and `KOSLI_ORG` should be set as [CI/CD variables](https://docs.gitlab.com/ci/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.
+
+  </Tab>
+</Tabs>
+
+## 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`](/client_reference/kosli_get_trail) reference.
+- Browse other [CI/CD integration patterns](/integrations/ci_cd).