Continuous integration¶
The
CI
workflow runs for pull requests, pushes to main, and manual dispatches.
Pull-request runs cancel older runs for the same branch.
| Required check | Coverage |
|---|---|
Backend |
Python 3.15 editable dev install, pip check, Ruff, the full pytest suite, and generated FastAPI OpenAPI drift |
Database migrations |
Python 3.15, a single Alembic head and alembic upgrade head against a clean Postgres 18 database |
Frontend |
Node.js 26, deterministic npm ci, moderate-or-higher npm advisories, generated TypeScript API drift, and the production build including TypeScript checking |
Containers |
PostgreSQL 17-to-18 volume migration, Compose validation, a no-cache image build, full stack startup, and backend plus nginx-proxied health checks |
The jobs use fixture-backed tests and empty provider configuration. No provider credentials or repository secrets are required. The backend/worker image also uses Python 3.15; the package minimum and Ruff syntax target remain Python 3.12.
The Tidal rate-limit test records and checks retry delays instead of waiting in
real time; production retry timing is unchanged. The frontend's npm run build
already runs tsc --noEmit, so CI does not run the same type-check twice.
After database migrations, Compose replaces the API and worker startup shells
with their application processes using exec. Shutdown signals reach those
processes directly, allowing graceful cleanup without waiting for the shell's
stop timeout. The container check still builds without cache and retains its
full smoke test.
Documentation and Pages¶
The
Documentation
workflow validates changes to docs/, mkdocs.yml, requirements-docs.txt, and
its own workflow file. It installs the pinned documentation requirements on
Python 3.15 and runs a clean python -m mkdocs build --strict, then checks that
neither OpenAPI contract is included in the site. API generation and drift checks
remain in CI; the documentation build does not generate or publish those contracts.
The build uses a dedicated pip download cache at .cache/pip-docs in the build
workspace so unrelated preloaded packages are not restored and saved with the
documentation dependencies. The existing setup-python cache still keys on
the runner platform, Python version, and requirements-docs.txt. Both cache hits
and misses run the same dependency installation and strict build; installed
environments and built sites are not cached.
Pull requests only build and validate, and newer runs cancel obsolete builds
for the same PR. Pushes to main and manual dispatches upload the checked site
as the run's github-pages artifact for the dependent deployment job. The
existing github-pages environment restricts deployment to main. Running
push/manual workflows finish before a newer run for the same ref starts; only
the newest pending run is retained.
For recovery, re-run a known-good deployment job while its artifact is available
(the Pages artifact retention is one day), or manually dispatch the workflow on
main to rebuild and deploy its current documentation. Do not dispatch a
deployment just to measure build performance.
Local equivalents¶
Backend:
cd backend
python3.15 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pip check
python -m ruff check .
python -m pytest
Regenerate and check the API contract after backend route or model changes:
cd backend
python - <<'PY'
import json
from pathlib import Path
from app.main import app
Path("../openapi/open-playlist-engine.json").write_text(
json.dumps(app.openapi(), indent=2, sort_keys=True) + "\n",
encoding="utf-8",
)
PY
git diff --exit-code -- ../openapi/open-playlist-engine.json
cd ../frontend
npm ci --no-audit --no-fund
npm audit --audit-level=moderate
npm run gen:api
git diff --exit-code -- src/api/schema.d.ts
npm run typecheck
npm run build
The container check exercises the PostgreSQL 17-to-18 dump/restore path before starting the application on PostgreSQL 18:
Future Postgres major versions remain manual upgrades because storage formats and volume layouts can change. Dependabot keeps Compose on the supported major while still proposing minor and patch updates.
cp .env.example .env
docker compose config --quiet
docker compose build --no-cache
docker compose up --detach postgres valkey backend
curl --fail http://127.0.0.1:8000/health
docker compose up --detach worker frontend
curl --fail http://127.0.0.1:8080/health
docker compose down --volumes