workflows

GitHub Actions workflows

Workflow files use a category prefix and live only in this directory (GitHub ignores subfolders).

Pipeline map: .github/CI-CD.md · Secrets: .github/ACTIONS-SECRETS.md

Naming convention

Prefix	Stage	Runbook
ci-	Continuous integration	ci/README.md
security-	Security	security/README.md
quality-	Quality & coverage	quality/README.md
deploy-	Deploy	deploy/README.md
release-	Release	release/README.md
ops-	Operations	ops/README.md
automation-	Automation	automation/README.md

Executable YAML: .github/workflows/<prefix>-<name>.yml (GitHub does not load subfolders).

Display names in GitHub UI follow Category / Name (e.g. CI / App, Quality / Codecov).

---

CI — continuous integration

Verify code before merge. Runbook: ci/README.md

Workflow	File	Job	Trigger paths (summary)
CI / App	ci-app.yml	App (lint · typecheck · build)	src/, server/, tests/, package.json, OpenAPI, …
CI / Docs	ci-docs.yml	Extended docs (MkDocs strict)	extended-docs/, docs/, agent/
CI / Docker smoke	ci-docker-smoke.yml	Docker image (build only)	Dockerfile, docker-compose*, server/

All support workflow_dispatch.

---

Security

Dependency audit, PR dependency review, SAST, and container scanning. Runbook: security/README.md

Workflow	File	Job	When
Security / npm audit	security-audit.yml	npm audit	PR/push (package*.json, .npmrc); weekly Mon
Security / pip audit	security-pip-audit.yml	pip audit	PR/push (extended-docs/requirements.txt); weekly Mon
Security / Dependency review	security-dependency-review.yml	dependency-review	Pull requests only
Security / CodeQL	security-codeql.yml	Analyze (JS · Python · Actions)	PR: path-filtered; push/schedule/dispatch: all three
Security / Container scan	security-container-trivy.yml	Trivy	PR/push (Docker paths); weekly Mon

---

Quality

Coverage, bundle analysis, and external quality gates. Runbook: quality/README.md

Workflow	File	Job	Secret
Quality / Codecov	quality-codecov.yml	Run tests and collect coverage	CODECOV_TOKEN
Quality / SonarCloud	quality-sonarcloud.yml	SonarCloud Code Analysis	SONAR_TOKEN

Codecov also runs npm run build for Vite bundle analysis (vite.config.ts). Config: root codecov.yml.

---

Deploy

Runbook: deploy/README.md

Workflow	File	When
Deploy / GitHub Pages	deploy-pages.yml	Push main (docs paths) or manual; release dispatches on main

One-time: Settings → Pages → GitHub Actions.

---

Release

Runbook: release/README.md

Triggered by semver tag v* (must match package.json version).

Workflow	File	Output
Release / GitHub	release-github.yml	GitHub Release, dist tarball, CycloneDX SBOM
Release / Docker Hub	release-docker-hub.yml	Docker image push + smoke test

---

Ops

Runbook: ops/README.md

Manual or docs-driven maintenance. Environment docker for Hub credentials.

Workflow	File	Purpose
Ops / Docker Hub metadata	ops-dockerhub-metadata.yml	Sync Hub overview from docs/dockerhub/
Ops / Docker Hub prune	ops-dockerhub-prune.yml	Remove extra tags

---

Automation

Runbook: automation/README.md

Workflow	File	Trigger
Automation / Issue summary	automation-issue-summary.yml	Issue opened (skip bots / no-ai-summary)

---

Engineering conventions

Practice	How
Flat layout	.github/workflows/<prefix>-<name>.yml
Pinned actions	uses: org/action@<sha> # vN
Least privilege	permissions: per workflow
Concurrency	cancel-in-progress: true on CI; false on Pages
Timeouts	timeout-minutes on every job
Secrets in if:	Never — use env + shell or continue-on-error

Path-filter cheat sheet

Change type	Typical workflows
App / server only	ci-app, quality-*, security-audit, security-dependency-review, CodeQL (JS)
Docs only	ci-docs, deploy-pages, security-pip-audit, CodeQL (Python)
Docker / Dockerfile	ci-docker-smoke, security-container-trivy
package-lock.json	ci-app, security-audit
Workflows only	CodeQL (Actions), affected workflow
Tag v*	release-*; release-github dispatches deploy-pages on main

Branch protection (ruleset main) requires job names below. For path-filtered PRs where a check did not run, use workflow_dispatch on that workflow before merge.

Required check	Workflow
App (lint · typecheck · build)	ci-app.yml
Run tests and collect coverage	quality-codecov.yml
SonarCloud Code Analysis	quality-sonarcloud.yml
Trivy	security-container-trivy.yml
Analyze (javascript-typescript)	security-codeql.yml
Analyze (python)	security-codeql.yml
Analyze (actions)	security-codeql.yml

Setup checklist

1. Pages: GitHub Actions source
2. Node.js: CI uses .nvmrc (24) via actions/setup-node — satisfies @eslint/* engine range and clears EBADENGINE warnings in Actions
3. Branch ruleset: active on main — see table above and CONTRIBUTING.md
4. Dependabot: .github/dependabot.yml
5. Optional secrets: CODECOV_TOKEN, SONAR_TOKEN, MERGIFY_TOKEN, DOCKERHUB_* — ACTIONS-SECRETS.md

Local parity

make check
make extended-docs-check
npm audit --omit=dev

See docs/CONTRIBUTING.md.