Set up CI

Store CASSIS_API_KEY as a CI secret and CASSIS_PROJECT_ID as a repository variable. Scope the key to that project. Install a pinned CLI version in each job.

Choose the right workflow

GitHub Actions

With the GitHub App

The App validates pull requests and publishes merges. Add only the eval suite:

name: Cassis context eval

on:
  pull_request:
    paths: ["cassis/**"]

permissions:
  contents: read

jobs:
  context-eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install "cassis-cli~=3.1"
      - run: cassis eval run
        env:
          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
          CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}

Require both the Cassis validation check and this eval job before merge.

Without the GitHub App

Use two workflow files: one validates pull requests, the other publishes after a merge to main. A single file with both triggers lists the job that did not apply as skipped on every run, so pull requests show a skipped publish and merges show a skipped check. Separate files list only the jobs that ran.

name: Cassis context check

on:
  pull_request:
    paths: ["cassis/**"]

permissions:
  contents: read

jobs:
  context-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install "cassis-cli~=3.1"
      - run: cassis verify
        env:
          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
          CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}

name: Cassis context publish

on:
  push:
    branches: [main]
    paths: ["cassis/**"]

permissions:
  contents: read

jobs:
  context-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install "cassis-cli~=3.1"
      - run: cassis context upload
        env:
          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
          CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}

Change main if your default branch has another name.

From cassis-cli 3.0.0, the upload records the commit actions/checkout checked out on the published version. It refuses to run outside a git checkout, or when files under cassis/ differ from that commit, so do not let an earlier step rewrite them.

GitLab CI

The same two stages work on GitLab:

context-check:
  image: python:3.12-slim
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - python -m pip install "cassis-cli~=3.1"
    - cassis verify
  variables:
    CASSIS_API_KEY: $CASSIS_API_KEY
    CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID

context-publish:
  image: python:3.12  # not -slim: the upload needs git
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - cassis/**/*
  script:
    - python -m pip install "cassis-cli~=3.1"
    - cassis context upload
  variables:
    CASSIS_API_KEY: $CASSIS_API_KEY
    CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID

The publish job uses the full python image because cassis context upload needs git from cassis-cli 3.0.0, and the -slim image lacks it. On another image, install it first, for instance apt-get update && apt-get install -y --no-install-recommends git.

Like the GitHub workflow, the publish job runs only when a push changes cassis/. An upload that changes nothing publishes no new version, but the published version records its commit, so cassis status shows that checkout in sync from cassis-cli 3.1.1. An older CLI compares against the commit of the last publish that changed the context and counts the commits since then as ahead.

Protect the default branch and require the validation job before merge. If a job fails, the CLI output distinguishes a context failure from missing credentials or an unreachable API; see Troubleshoot git and publishing.

A publish that fails on the server now fails the publish job and prints the server’s reason. This needs cassis-cli 1.6.0 or later. On an older version, a failure that happened after the upload started processing could leave the job green even though nothing was published.