Docs/Deployment/CI/CD Pipelines

CI/CD Pipelines

Eight GitHub Actions workflows live in .github/workflows/. Pull requests are gated by CI, whose summary job CI OK also covers the static gates, secret scan, DCO sign-off, dependency review and docs link check; CodeQL reports separately. Tagging vX.Y.Z runs Release, which publishes signed multi-arch images and Helm charts to GHCR. There is no hosted deploy pipeline in this repository: deployment is yours, using Docker Compose or the Helm charts (see the Deployment Guide).

Source of truth

Triggers and job names below were read from the workflow files. If this page and a workflow file disagree, the file wins.

Required checks: CI OK (the ci-ok job in ci.yml) and CodeQL OK (codeql.yml); see CONTRIBUTING.md
Registry: GHCR (ghcr.io/<owner>), images and OCI Helm charts, published only by release.yml
Supply chain: cosign keyless signatures, SPDX SBOM attestations, SLSA build provenance
Local equivalents: make test, make lint, make gates, make compose-validate, make helm-lint, make sbom

All workflows

File	Trigger	What it does
`ci.yml` (CI)	pull request; push to `main`; dispatch	Path-filtered build and test (below). Concurrency cancels superseded runs on pull requests.
`static-gates.yml`	called by `ci.yml` (`workflow_call`); dispatch	Job `Static gates`: Flyway migration lint (uploads the checksum lock), duplicate bean/entity name guard, entity/table/bean/path namespace lint, expired test-skip check, file-size ratchet. Job `Secret scan`: gitleaks over new commits.
`codeql.yml`	pull request; push; weekly (Monday 04:27 UTC); dispatch	CodeQL SAST for java-kotlin, javascript-typescript and python, build-mode none.
`scorecard.yml`	weekly (Tuesday 05:41 UTC); push; dispatch	OpenSSF Scorecard analysis; SARIF uploaded.
`release.yml`	tag `v..*`; dispatch with an existing `tag`	Publishes images, charts, SBOMs and the source tarball (below).
`e2e.yml`	nightly (03:17 UTC); dispatch	Builds the compose stack from the commit (full stack + build + CI overlays with a mock OpenAI-compatible provider), waits for health, runs the Playwright suite in `tests/e2e`. Dispatch inputs choose compose files, profiles and specs.
`labeler.yml`	pull request target (opened, synchronize, reopened)	Applies labels with `actions/labeler`.
`stale.yml`	daily (06:33 UTC); dispatch	Marks issues and PRs stale after 60 days, closes 14 days later; exempts pinned, security, roadmap and similar labels, and draft PRs.

CI — job graph

flowchart LR
  A[changes: path filter] --> B[core / web / web-admin / python / node-services]
  A --> C[shellcheck / hadolint / compose / helm]
  A --> E[static-gates / dco / dependency-review / docs-links]
  B --> D[CI OK]
  C --> D
  E --> D

Job	What it does
`changes`	Uses `dorny/paths-filter` to decide which areas changed (core, web, web-admin, python services, node services, shell, docker, compose, helm). A change to `ci.yml` or `scripts/ci/` triggers everything.
`core`	Maven verify on JDK 21 against Postgres with pgvector and Apache AGE; uploads test reports.
`web`, `web-admin`	Node 22: lint, typecheck, test, build.
`python`	ruff; sidecar pytest (CPU-only torch); code-intel script harness (not pytest).
`python-extra`	Other Python services (app-builder, tool-sandbox, voice-agent), one matrix leg each; part of `CI OK`.
`node-services`	mcp-stdio-runner (`node:test`), the home-assistant example MCP server; http-gateway is advisory.
`shellcheck`, `hadolint`	Shell scripts at severity error; Dockerfile lint.
`compose`	`docker compose config` on the files in `deploy/compose`.
`helm`	helm lint, template and kubeconform via `scripts/ci/helm-validate.sh`, plus render-guard negative tests when `deploy/helm/test-guards.sh` exists.
`static-gates`	Runs `static-gates.yml` as a reusable workflow (static gates and gitleaks secret scan).
`dco`, `dependency-review`	DCO sign-off check on the commits; dependency review of the pull request.
`docs-links`	lychee in offline mode (with fragments) over `.md`, `docs//.md` and `docs/*/.html` — this handbook included.
`CI OK`	Aggregates the job results above (areas with no changes are skipped). This is the single check to require in branch protection.

Release — what a tag produces

flowchart LR
  P[prepare] --> B[build per image x arch]
  B --> M[publish: multi-arch manifest, sign, SBOM, provenance]
  P --> C[charts: package, push OCI, sign]
  M --> R[GitHub Release]
  C --> R

Images. Built natively on amd64 and arm64, merged into one multi-arch manifest per image under ghcr.io/<owner>: core, core-worker, core-jobs, web, web-admin, sidecar, code-intel, app-builder, tool-sandbox, mcp-stdio-runner, voice-agent, rl-trainer, postgres, and a CloudNativePG operand variant (postgres:16-pgvector-age-<version>). Versions containing - are prereleases and do not move latest.
Signing. Each manifest is signed with cosign keyless (GitHub OIDC, Sigstore Fulcio and Rekor).
SBOM and provenance. An SPDX JSON SBOM (syft) is attested per image, and SLSA build provenance is attached.
Helm charts. Packaged by scripts/ci/helm-package.sh, pushed to oci://ghcr.io/<owner>/charts, signed, with provenance.
GitHub Release. Attaches the SBOMs, chart archives, and the source tarball vegaduta.tar.gz (with SHA256SUMS) that install.sh downloads.

cosign verify ghcr.io/<owner>/core:<version> \
  --certificate-identity-regexp '^https://github.com/<owner>/<repo>/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify oci://ghcr.io/<owner>/core:<version> --repo <owner>/<repo>

Running the same checks locally

CI job	Local command
Static gates and secret scan	`make gates` (enable the pre-push hook with `make hooks`)
core, web, web-admin, python tests	`make test` (or `make test-core`, `test-web`, `test-web-admin`, `test-python`)
Lint, typecheck, ruff, shellcheck	`make lint`
compose validation	`make compose-validate`
helm validation	`make helm-lint`
Source SBOM	`make sbom` (writes `dist/sbom-source.spdx.json`)

Not covered by any pipeline

Deploying. No workflow deploys to any environment. You run Compose or Helm against your own infrastructure.
Database migrations. Flyway runs inside core at startup; flyway-lint.sh catches shared-namespace collisions and edits to applied migrations, not runtime conflicts.
Translations. Message catalogs can be regenerated by maintainers; no workflow does it.

Evidence & references

.github/workflows/ci.yml, static-gates.yml, codeql.yml, scorecard.yml, release.yml, e2e.yml, labeler.yml, stale.yml — triggers and job names.
Makefile, CONTRIBUTING.md, scripts/ci/ — local equivalents and gate scripts.