129 lines
5.0 KiB
Markdown
129 lines
5.0 KiB
Markdown
# CI and supply-chain release gates
|
|
|
|
GeoIntel uses the same release gates in Gitea Actions and GitHub Actions:
|
|
|
|
- `.gitea/workflows/release-gates.yml`
|
|
- `.github/workflows/release-gates.yml`
|
|
|
|
Gitea is the operational source-control platform. The GitHub workflow is kept
|
|
equivalent so a mirror or external review does not receive a weaker gate.
|
|
|
|
## Runner requirements
|
|
|
|
The `ubuntu-latest` runner must provide:
|
|
|
|
- outbound HTTPS access to PyPI, npm, Docker Hub and vulnerability databases;
|
|
- Python 3.11 and Node 20 through the official setup actions;
|
|
- Bash and Docker with Compose v2;
|
|
- permission to build images and mount `/var/run/docker.sock`;
|
|
- sufficient disk for the all-in-one GIS image and scanner databases.
|
|
|
|
The container job builds the GIS release variant only. PyTorch and
|
|
Ultralytics remain in the optional `ai` extra and in the explicit AI image
|
|
variant; CI does not silently make them base dependencies.
|
|
|
|
## Quality gate
|
|
|
|
The quality job installs:
|
|
|
|
```bash
|
|
python -m pip install --require-hashes -r backend/requirements-ci.lock
|
|
python -m pip install --no-deps -e backend
|
|
cd frontend && npm ci
|
|
```
|
|
|
|
It then validates the lock policy and runs the complete readiness script. The
|
|
readiness script covers backend compile/tests, contract audits, Alembic
|
|
single-head, frontend typecheck/build and release-script syntax. CI also
|
|
renders offline migration SQL and resolved Compose configuration as retained
|
|
evidence.
|
|
|
|
## Reproducible Python lock
|
|
|
|
`backend/requirements-runtime.lock` and `backend/requirements-ci.lock` are
|
|
generated in a digest-pinned Linux Python 3.11 container. The runtime lock
|
|
contains base and GIS packages used by the release image. The CI lock adds
|
|
developer/test dependencies. Both use package hashes and deliberately exclude
|
|
the optional AI dependency group.
|
|
|
|
Regenerate after changing relevant `pyproject.toml` dependencies:
|
|
|
|
```bash
|
|
bash scripts/generate_python_lock.sh
|
|
python scripts/verify_python_lock.py
|
|
```
|
|
|
|
The all-in-one frontend build uses `npm ci`; the non-AI runtime installs the
|
|
hashed runtime lock. The optional AI image additionally uses explicit
|
|
PyTorch, torchvision and Ultralytics build-argument versions.
|
|
|
|
Do not hand-edit dependency versions or hashes in either generated lock.
|
|
`verify_python_lock.py` rejects a stale input fingerprint, another Python
|
|
generation version, unhashed packages, missing direct dependencies and AI
|
|
packages leaking into the standard CI environment.
|
|
|
|
## Vulnerability policy
|
|
|
|
The dependency job:
|
|
|
|
- fails on any non-excepted vulnerability reported by `pip-audit` for the
|
|
complete exact lock without platform-specific re-resolution;
|
|
- fails when `npm audit --audit-level=high` finds a high or critical frontend
|
|
dependency vulnerability;
|
|
- publishes both unfiltered and policy-filtered Python JSON reports plus the
|
|
npm JSON report, including on failure.
|
|
|
|
The only current Python/container exceptions are the Starlette 2026 advisories recorded
|
|
in `security/pip-audit-exceptions.json`. FastAPI 0.139.2 still constrains
|
|
Starlette below 0.53 while patched releases begin at 1.x. GeoIntel applies
|
|
request-target, form-content, route-class and Linux-runtime compensating
|
|
controls. The exception file has a mandatory review date; readiness and CI
|
|
fail automatically after it expires. New advisories are never auto-ignored.
|
|
The all-in-one image replaces the Go-based base-image `gosu` helper with a
|
|
small `setpriv` exec wrapper and upgrades packaged setuptools/wheel metadata;
|
|
the final runtime filesystem no longer exposes the vulnerable Go executable.
|
|
Because OCI layers are immutable, Trivy still records the shadowed Go binary
|
|
from the official Postgres base layer in the complete JSON report. The
|
|
release-policy pass skips only `/usr/local/bin/gosu` after the final image is
|
|
verified to contain the audited shell wrapper. This is not a vulnerability
|
|
exception: the raw evidence remains published and the runtime wrapper is
|
|
exercised during live release validation.
|
|
|
|
The container job builds a non-AI all-in-one image and uses digest-pinned
|
|
scanner images:
|
|
|
|
- Syft 1.44.0 generates an SPDX JSON SBOM;
|
|
- Trivy 0.70.0 generates a complete JSON vulnerability report;
|
|
- fixed high or critical image vulnerabilities fail the gate;
|
|
- unfixed findings remain in the full report and require explicit release
|
|
review, but do not make a rebuild impossible when no patched package exists.
|
|
|
|
Run these controls on a Docker-enabled workstation:
|
|
|
|
```bash
|
|
docker build \
|
|
-f deploy/unraid/Dockerfile.all-in-one \
|
|
--build-arg GEOINTEL_INSTALL_AI=false \
|
|
--build-arg GEOINTEL_BUILD_SHA=local \
|
|
--build-arg GEOINTEL_BUILD_TIME=local \
|
|
-t geointel-ci:local .
|
|
bash scripts/generate_container_sbom.sh geointel-ci:local
|
|
bash scripts/scan_container_image.sh geointel-ci:local
|
|
```
|
|
|
|
Outputs are written below ignored `artifacts/`; scanner cache is written below
|
|
ignored `.cache/trivy/`.
|
|
|
|
## Published evidence
|
|
|
|
Every workflow run retains:
|
|
|
|
- offline Alembic upgrade SQL;
|
|
- resolved Docker Compose configuration;
|
|
- pip-audit and npm-audit JSON;
|
|
- image inspection metadata;
|
|
- SPDX JSON SBOM;
|
|
- complete Trivy JSON report.
|
|
|
|
No secret or plaintext database credential belongs in these artefacts.
|