diff --git a/config/navigation.json b/config/navigation.json index b436386..18c62b1 100644 --- a/config/navigation.json +++ b/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" ] }, { diff --git a/integrations/ci_cd.md b/integrations/ci_cd.md index 0c10cdd..67e5a6f 100644 --- a/integrations/ci_cd.md +++ b/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 diff --git a/labs/lab-02-flows-and-trails.mdx b/labs/lab-02-flows-and-trails.mdx index f537718..c292e0f 100644 --- a/labs/lab-02-flows-and-trails.mdx +++ b/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: | diff --git a/labs/lab-03-build-controls.mdx b/labs/lab-03-build-controls.mdx index 4fdf84a..6ca4703 100644 --- a/labs/lab-03-build-controls.mdx +++ b/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: | diff --git a/labs/lab-04-release-controls.mdx b/labs/lab-04-release-controls.mdx index 59587b0..9012b5c 100644 --- a/labs/lab-04-release-controls.mdx +++ b/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: | diff --git a/tutorials/linking_trails_across_branches.md b/tutorials/linking_trails_across_branches.md index d47c6fc..245bd2a 100644 --- a/tutorials/linking_trails_across_branches.md +++ b/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 diff --git a/tutorials/report_k8s_envs.md b/tutorials/report_k8s_envs.md index 31a2b22..f39999c 100644 --- a/tutorials/report_k8s_envs.md +++ b/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 diff --git a/tutorials/trail_summaries_in_ci.md b/tutorials/trail_summaries_in_ci.md new file mode 100644 index 0000000..9c69f57 --- /dev/null +++ b/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: ` 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 + + + + +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. + + + + +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. + + + + +## 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).