/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

GitHub Actions CI

Keywords on this page
WordMeaningExample
WorkflowOne YAML file in .github/workflows/, started by an eventci-gate.yml
JobOne unit of work in a workflow, on its own runnerchanges, telemetry
LegA job of the gate that checks one part of the repoThe twin leg
Reusable workflowA workflow other workflows call with uses:, like a functiontpl-rust-ci.yml
Composite actionA short list of steps shared by several workflows.github/actions/setup-rust
RunnerThe fresh virtual machine a job runs onubuntu-latest; Rust jobs and the acceptance suite pin ubuntu-22.04: MongoDB 8 refuses to start on Linux kernels 6.19 to 7.0.13 (SERVER-121912), and the 24.04 and 26.04 runners ship 7.0.0
Path filterA rule that says “this area changed” when a file under a path changedbackend/telemetry/**
MatrixOne job run once per item of a listOne Docker build per changed image
ArtifactA file a job uploads so a later job can download itthe telemetry coverage report
GHCRGitHub’s container registry, where images are storedghcr.io/nickghignatti/ambitwin-telemetry
RulesetGitHub settings that say what a merge into master needs“CI Passed” must be green

Ambitwin’s CI runs on GitHub Actions. It checks every pull request into master, then publishes images, coverage and the docs site after the merge. Every workflow reads one file to know the services: .github/services.json.

Related pages: Release Please, Dependencies & Security.


The workflows

Each file name starts with its kind.

KindStarted byFiles
ci-A pull request, or a call from ci-gate.ymlci-gate, ci-frontend, ci-docker, ci-k8s, ci-infra, ci-simulators, ci-acceptance, ci-docs, ci-dependency-review, ci-codeql
tpl-A call only: reusable workflow per languagetpl-rust-ci, tpl-go-ci, tpl-python-ci, tpl-node-ci, tpl-*-coverage
cd-A push to mastercd-registry, cd-release, cd-coverage, cd-documentation
maint-A weekly timermaint-renovate, maint-cleanup
WorkflowWhenWhat it does
ci-gate.ymlPR into masterFinds what changed, runs only those checks, reports one result: CI Passed
ci-codeql.ymlPR into master, Monday 03:00, by handSecurity scan of the source, 4 languages
cd-registry.ymlPush to master touching backend/, simulators/, frontend/Publishes images to GHCR
cd-release.ymlEvery push to masterRelease Please: release PR, tag, changelog
cd-coverage.ymlEvery push to master, by handMeasures coverage, publishes it on branch coverage-data
cd-documentation.ymlPush to master touching the docsBuilds this site, publishes it to GitHub Pages
maint-renovate.ymlMonday 02:00, by handOpens dependency update PRs
maint-cleanup.ymlSunday 02:00, by handDeletes old image versions from GHCR, keeps 3 and latest

The service list: .github/services.json

One entry per buildable part. Every workflow reads it, so a new service is one entry, not an edit in each workflow.

FieldMeaningExample
keyShort name, also the path filter nametwin
dirWhere it livesbackend/digital-twin
langPicks the reusable workflow and the Docker reciperust, go, python, node, frontend
imageImage name; no field means no imageambitwin-twin
cd_context, dockerfileBuild context and Dockerfile for cd-registry., backend/digital-twin/Dockerfile
needs_mongo, needs_redis, needs_postgres, needs_kafkaContainers the Rust tests neednotification: Mongo, Redis, Kafka
depends_onFolders it builds or tests from; their changes select it too. Must cover every local replace and Cargo pathtenancy: backend/libs/auth-middleware, schemas/fixtures
cifalse: no gate leg and no PR imagethe three simulators

Example. telemetry has needs_redis, needs_postgres, needs_kafka. Its gate leg starts Redis, TimescaleDB and Kafka before the integration tests. socket has only needs_redis, so its leg starts Redis only.


A pull request, from push to green

sequenceDiagram
    autonumber
    participant D as Developer
    participant GH as GitHub
    participant C as changes
    participant L as Service legs
    participant X as Other legs
    participant K as docker
    participant P as CI Passed
    D->>GH: push to a branch with an open PR into master
    GH->>C: start ci-gate.yml, cancel the older run on the same branch
    C->>C: filter-services builds one path filter per services.json key, dependencies included
    C->>C: dorny/paths-filter compares the PR diff with every filter
    C->>C: jq builds the Docker matrix from changed keys that have an image
    C-->>L: one true or false output per area
    par only the changed areas
        L->>L: tpl-rust-ci, tpl-go-ci, tpl-python-ci or ci-frontend
    and
        X->>X: k8s, infra, simulators, acceptance, docs, dependency-review, workflows-lint
    end
    L-->>K: legs done, none failed
    K->>K: build image, Trivy scan, push pr-HEADSHA tag
    L-->>P: success, failure or skipped
    X-->>P: success, failure or skipped
    K-->>P: success, failure or skipped
    P->>P: changes must be success, every other job success or skipped
    P-->>GH: CI Passed
    GH-->>D: merge allowed, squash only
StepWhat happens, with real values
2concurrency: ci-gate-${{ github.ref }}, cancel-in-progress: true: a new push stops the old run
3.github/actions/filter-services runs scripts/service-filters.py: one filter per entry, its dir plus its depends_on, for example telemetry: + - "backend/telemetry/**", - "schemas/claims-schema/**", - "schemas/fixtures/**", … The script fails the job first if depends_on disagrees with the code. Then the action adds the gate’s own filters: k8s, ci, infra, simulators, acceptance, docs, deps
4Output changes, a JSON list, for example ["telemetry","deps"]
5Changed keys with an image and no ci: false, for example {"include":[{"image":"ambitwin-telemetry","lang":"rust","context":".","dockerfile":"backend/telemetry/Dockerfile"}]}
7One job per changed service. Libraries and schema crates also have legs
8Each extra area has its own leg, see below
10ci-docker.yml, one matrix entry per image, see “Images on a pull request”
14A shell loop over needs.*.result
15The only required check in the master ruleset is CI Passed

Which legs run

A leg runs when its own dir changed, or a folder in its depends_on changed. Every service leg’s condition is just its own key; the dependencies live in .github/services.json, not in ci-gate.yml.

flowchart TD
    F["file changed in the PR"] --> A{"under a dir or a depends_on folder?"}
    A -- yes --> S["every key listing it is changed: its leg, image and coverage rerun"]
    A -- no --> B{"matches an extra filter?"}
    B -- yes --> E["that leg runs: k8s, docs, infra, ..."]
    B -- no --> N["nothing runs for it"]

depends_on cannot drift from the code. Before printing the filters, scripts/service-filters.py fails the changes job when:

A listed service passes its own service dirs on: tenancy lists auth-middleware, so it is also selected by auth-contracts. Plain folders do not pass on: auth-contracts’ fixtures feed its own tests, not the code its consumers compile.

Why: a dependency bump in auth-middleware once passed its own leg, skipped tenancy and claims-gateway, and left both unbuildable on master (missing go.sum entry), unnoticed until a later run rebuilt every service. The hand-written conditions it slipped through had four more holes of the same kind.

What the current depends_on gives:

Change inLegs that also runWhy
backend/libs/auth-contractsauth-middleware, auth-policy, claims-gateway, provisioner, registry, tenancyThey build against its source through a local replace
backend/libs/auth-middlewareclaims-gateway, tenancyLocal replace; its dependency versions must reach their go.sum
backend/libs/auth-policytenancyLocal replace: the Cedar bundle tenancy evaluates
schemas/claims-schemachat, notification, telemetry, socket, twin, dashboardEvery Rust service parses claims with it
schemas/telemetry-schemanotification, telemetry, socket, twin, dashboardThey share the tick and alert shapes
schemas/twin-schematelemetry, socket, twinRegistration, Wi-Fi and device shapes
schemas/fixtures/**, schemas/json/**Every leg whose tests replay a fixture: frontend, agent, ap-collector, tenancy, auth-contracts, the four schema crates, chat, notification, telemetry, socket, twin, and the simulators legA fixture change must fail every language that disagrees

Example. A PR changes only schemas/twin-schema/src/wifi.rs. Keys changed: twin-schema, telemetry, socket, twin. Legs that run: those four. PR images built: ambitwin-telemetry, ambitwin-socket, ambitwin-twin, because they compile the crate; twin-schema has no image.

Why one gate job

ci-passed waits for every leg with if: always(), so it runs even when legs are skipped.

RuleWhy
changes must be successIf it failed, every leg was skipped without being judged. Green there would be a lie
Every other result must be success or skippedA list of good results, not of bad ones: cancelled or any new value fails too
Only CI Passed is requiredThe ruleset names one check, so adding or removing a leg never touches GitHub settings

A leg nobody waits for passes silently

needs: cannot be computed, so every service job is written three times in ci-gate.yml: as a job, in docker.needs, in ci-passed.needs. A job missing from a list still runs, but the gate goes green without it. scripts/check-workflow-registry.py, run by the workflows-lint leg and by just lint workflows (also before just lint all and just lint affected), compares the three lists with services.json and fails on any gap.


The language legs

Each language has one reusable workflow. The gate calls it with service_key and working_directory.

tpl-rust-ci.yml

sequenceDiagram
    autonumber
    participant G as ci-gate
    participant T as tpl-rust-ci
    participant I as Containers
    G->>T: service_key telemetry, working_directory backend/telemetry
    T->>T: jq reads needs_* for telemetry in services.json
    T->>I: setup-redis, setup-postgres, setup-kafka
    T->>T: setup-rust: toolchain from the mise pins, rust-cache per service
    T->>T: cargo fmt --check
    T->>T: cargo clippy --release --all-targets -- -D warnings
    T->>T: cargo audit, two advisories ignored
    T->>T: cargo test --release --lib, or --bins with no lib.rs
    T->>T: scripts/test/rust-integration-tests.sh --release
StepDetail
3setup-mongo runs mongo:8.3.9, setup-redis runs redis:8.10.1-alpine, each waits until it answers
4Version from the rust = "…" line of .mise.toml. Swatinem/rust-cache, key rust-ci-telemetry
7Ignores RUSTSEC-2023-0071 and RUSTSEC-2026-0387: both reach notification through web-push and have no usable fix. Ignores RUSTSEC-2026-0459 too: libsqlite3-sys is in Cargo.lock for sqlx’s sqlite driver, which no service compiles
8--lib fails on a crate with no lib.rs, so dashboard runs --bins
9Runs each tests/*.rs by name, so unit tests are not run twice. Env: MONGO_URI=mongodb://localhost:27017, REDIS_URL, DATABASE_URL=postgres://postgres:telemetry@localhost:5432/telemetrydb, KAFKA_BROKERS=localhost:9092

The other languages

WorkflowSteps, in orderBlocks on
tpl-go-ci.ymlsetup-go (version from .mise.toml, Go module cache), gofmt -l loop, go vet, govulncheck, go build, go test -tags=integration ./...Everything except govulncheck, which is continue-on-error
tpl-python-ci.ymlsetup-python (.python-version, uv cache, uv sync --locked), ruff check, ruff format --check, pyright, uv audit, pytestEverything. Builds no artifact
ci-frontend.ymlJob quality: npm ci, lint, type-check, npm audit --omit=dev. Job test: Vitest in 3 shardsEverything except the full npm audit including dev deps
tpl-node-ci.ymlLint, build, test, audit, upload dist-<key>Not called by any workflow

Other legs of the gate

LegRuns whenWhat it checks
k8s (ci-k8s.yml)k8s/**kubeconform -strict against Kubernetes 1.32.0 plus the CRD catalog for Istio kinds, pluto for removed APIs, kube-score with 7 tests ignored
infra (ci-infra.yml)scripts/**, tooling/**, Justfilenode --check on JS, bash -n on shell, each scripts/test_*.py, just --summary
simulators (ci-simulators.yml)simulators/**sensor-simulator: lint, build, test. aq-simulator and ap-simulator: ruff check, pyright, uv audit, pytest
acceptance (ci-acceptance.yml)backend/acceptance/**, Caddyfile, k8s/istio-request-authentication.yml, telemetry, socket, dashboard, devices/ap-collectorbackend/acceptance/run-integration-tests.sh: a composed stack with a real Caddy edge. 45 min limit, the slowest leg
docs (ci-docs.yml)documentation/**, api/**, the docs recipe, .mise.tomljust docs build, with the Quarkdown version read from .mise.toml
dependency-reviewAny manifest or lockfileSee Dependencies & Security
workflows-lint.github/**actionlint (shellcheck off), zizmor --min-severity medium, check-workflow-registry.py

Images on a pull request

ci-docker.yml runs after the legs, once per changed image, when no leg failed.

sequenceDiagram
    autonumber
    participant G as ci-gate docker job
    participant B as ci-docker rust-base
    participant W as ci-docker build
    participant T as Trivy
    participant R as GHCR
    G->>B: matrix holds a rust image
    B->>R: ambitwin-rust-base RUSTPIN-HASH exists? push it if not
    G->>W: matrix entry ambitwin-telemetry, backend/telemetry/Dockerfile, context .
    W->>W: buildx build with rust-base, load locally, gha cache scope ambitwin-telemetry
    W->>T: scan OS packages, HIGH and CRITICAL with a fix
    alt finding
        T-->>W: exit 1, the leg fails, nothing is pushed
    else clean
        W->>R: push ambitwin-telemetry:pr-HEADSHA
    end

A merge, through to published images

sequenceDiagram
    autonumber
    participant M as master
    participant C as cd-registry changes
    participant B as rust-base
    participant P as build-and-push
    participant R as GHCR
    M->>C: push after the squash merge
    C->>C: filter-services on the pushed commit
    C->>C: build the matrix from services.json
    C->>B: any image selected
    B->>R: ambitwin-rust-base RUSTPIN-HASH exists?
    alt missing
        B->>R: build docker/rust-base and push it
    end
    C->>P: one job per image
    P->>P: gh api commits/SHA/pulls gives the PR head SHA
    P->>R: does ambitwin-telemetry:pr-HEADSHA exist?
    alt found
        P->>P: Trivy scan of the pr image, SARIF to the Security tab
        P->>R: imagetools create --prefer-index=false, latest and SHA tags, no rebuild
        P->>R: every manifest under latest still resolves?
    else not found
        P->>P: build from backend/telemetry/Dockerfile with rust-base
        P->>P: Trivy scan
        P->>R: push latest and SHA
    end
StepDetail
3workflow_dispatch with service: all or a list such as twin,frontend. A change to services.json or cd-registry.yml selects every image
5Tag = rust pin from .mise.toml + first 12 characters of the sha256 of docker/rust-base/Dockerfile. An unchanged base is never rebuilt
8A squash merge makes a new commit, so the PR’s head SHA is looked up through the API
10Same Trivy settings as on the PR; the result also goes to the Security tab
11A carbon copy: latest, the SHA and pr-HEADSHA end up on one registry version, the very image scanned on the PR
12Fails the job if latest points at a manifest that is gone
15Happens on a manual run, or when the PR image is missing. frontend gets VITE_VAPID_PUBLIC_KEY as a build arg

Never delete the pr version after promoting it

A promotion that wrote a new index would borrow the pr-HEADSHA version’s manifests. Deleting that version then left latest pointing at nothing: docker pull fails with manifests/sha256:… not found. That is why the copy is exact and no step deletes the pr tag. maint-cleanup.yml uses dataaxiom/ghcr-cleanup-action, which keeps every manifest a kept tag still needs.


Coverage after a merge

cd-coverage.yml measures coverage on master only. Pull requests never measure it, and no threshold blocks anything.

  1. load-registry path-filters the push and splits the changed services by lang into four lists.
  2. One tpl-<lang>-coverage.yml call per non-empty list. An empty list skips the job: GitHub fails a reusable workflow called with an empty matrix.
  3. publish downloads the reports and fetches the previous coverage-counts.json and reports/ from branch coverage-data.
  4. scripts/coverage-summary.py merges new counts over the old ones and rewrites reports/<service>.json for the services that ran, so unchanged services keep their numbers and their per-file report.
  5. The result, badge.json, summary.json, coverage-counts.json and reports/, is force-pushed as a single commit to coverage-data, with 3 attempts.

Example. A push changes telemetry only. rust gets one entry, node, python, go are skipped. The badge is recomputed from the new telemetry counts plus last run’s counts for every other service.


Speed: caches and skipping

WhatHow
Skip unchanged partsPath filters per service; ci-passed treats skipped as fine
RustSwatinem/rust-cache, one key per service
Goactions/setup-go cache keyed on go.sum
Pythonsetup-uv cache keyed on uv.lock
Nodeactions/setup-node npm cache keyed on package-lock.json
Dockertype=gha layer cache, one scope per image, same scope on PRs and master, so a PR reuses master’s layers
No double buildcd-registry promotes the PR image instead of rebuilding it
Stop stale runscancel-in-progress on the gate and on CodeQL

Permissions

RuleWhereWhy
Read-only token by defaultci-gate.yml: contents: read, pull-requests: readA PR’s code runs with the smallest rights
packages: write only where pushingdocker job, cd-registry, maint-cleanupOnly those touch GHCR
CodeQL in its own workflowci-codeql.yml with security-events: writeA called workflow cannot get more rights than its caller, and the gate stays read-only
persist-credentials: false on every checkoutAll workflowsThe token is not left on disk for later steps
Values through env:, never inline in run:All workflowsStops template injection; zizmor checks it
Third-party actions pinned to a commit SHAAll workflowsA tag can be moved to other code; a SHA cannot
PAT secretsSEMANTIC_RELEASE_TOKEN, RENOVATE_TOKENPRs opened with the default token start no workflows

What blocks a merge into master

From the repository rulesets:

RuleValue
Required checkCI Passed, up to date with master
Code scanningCodeQL: security alerts high or higher, or any error-level alert
Merge methodSquash only, linear history
ReviewsA pull request is required; 0 approvals
BranchNo deletion, no force push

Traps


Reproducing locally

CI legLocal command
A service legjust test <svc>, then just test <svc>-integration
All changed partsjust test affected, just lint affected
workflows-lint registry checkjust lint workflows
docsjust docs build
acceptancejust test integration
Lockfiles and auditjust setup deps-check, just setup audit

The gate skill runs the checks in CI order and stops at the first failure.