Skip to content

GitHub Actions — Cassian Gate gate template

This document describes a GitHub Actions pattern for running Cassian Gate as a deterministic, clean-state validation gate.

It is a supporting CI guide. It does not replace deterministic execution, authoritative artifacts, or the project design contract.

What this workflow is for

Use this pattern when you want a CI job to:

  • validate topology input before execution
  • run the authoritative gate with cassian test
  • preserve generated artifacts for audit and debugging
  • avoid treating exploratory workflows as deployment authority

What this workflow is not

This workflow is not:

  • a broad CI automation framework
  • a substitute for the Cassian Gate authority model
  • a reason to treat cassian run as a gate
  • a promise that every GitHub-hosted runner shape supports containerlab reliably

Authority rules

Keep these boundaries explicit:

  • authoritative gate execution runs through cassian test <topology.yaml>
  • cassian run remains exploratory and non-authoritative
  • results.json remains the authoritative verdict artifact
  • results.summary.txt remains explanatory only
  • labs/ remains generated evidence only

Runner requirements

This pattern is generally intended for a Linux environment with the privileges needed by the current Cassian Gate runtime.

Typical requirements include:

  • Linux host or runner
  • Docker available to the runner
  • containerlab installed ahead of time
  • sufficient privileges for containerlab networking

Self-hosted runners are typically the most practical choice.

Typical CI shape

A narrow, truthful CI flow usually looks like this:

  1. install pinned Python dependencies
  2. run repository verification or syntax checks as needed
  3. validate the topology
  4. run the authoritative gate with cassian test
  5. assert render determinism with a clean-state replay byte-identity check
  6. upload generated artifacts for review

Determinism replay check (B-9)

The gate job includes a replay determinism check. It runs a by-design failing-invariant topology through two independent clean-state up → test → down cycles and fails the step on any byte-difference in the rendered results.summary.txt across the two runs.

The verdict is FAIL by design and is not what this step asserts — it asserts byte-identity of the rendered failure surface (the observed: blocks), not the verdict. Per the determinism contract in docs/topology-schema-v1.5.md §3.2, environmental tokens never enter that surface, so two clean runs render identically; any difference fails the gate.

Example local reproduction

From repo root:

1
2
3
4
5
python -m py_compile src/*.py
bash scripts/verify_phase1.sh

cassian validate topologies/three-frr-two-hosts-fw-routed.yaml
cassian test topologies/three-frr-two-hosts-fw-routed.yaml --scenario quick_all

This keeps CI aligned to the authoritative gate surface.

Example artifact upload set

Typical artifact upload choices include:

  • labs/**/results.json
  • labs/**/results.summary.txt
  • labs/**/topology.resolved.yaml
  • labs/**/artifacts/**

If your storage policy allows it, you may also retain the broader labs/** directory on failure for debugging.

Important boundary

This page is supporting guidance only.

Deploy/no-deploy meaning still comes from:

  • deterministic execution
  • cassian test
  • authoritative generated artifacts, especially results.json