Skip to content

WORKFLOWS.md

Latest commit

 

History

History
101 lines (73 loc) · 6.38 KB

WORKFLOWS.md

File metadata and controls

101 lines (73 loc) · 6.38 KB

CI/CD workflows

GitHub Actions and CI/CD helpers for this repository (see .github/ for workflow YAML).

Workflows

File Role
workflows/ci.yml Umbrella CI — runs on push/PR to main and develop
workflows/cd.yml Deploy — after CI succeeds on push to develop (staging) or main (production); inline SSH script parameterized by branch
workflows/promote-main.yml Promote to production — manual workflow_dispatch; ff-only develop → main via PROMOTE_PAT so CI and cd.yml run on main
workflows/release.yml Release — manual workflow_dispatch only; tags main from pyproject.toml (v<version>) and creates a GitHub Release with Weblate compatibility metadata
workflows/ci-lint.yml Lint and format (prek)
workflows/ci-test.yml Unit tests and coverage
workflows/ci-package.yml Build and package checks
workflows/ci-dependencies.yml Dependency and license audit
workflows/ci-weblate-pin.yml Weblate version sync — callable from CI; runs scripts/check-weblate-pin-sync.sh so pyproject.toml and Dockerfile.weblate-plugin pins match
workflows/weblate-pin-bump.yml Scheduled Weblate pin bump (PyPI + Docker + uv.lock)
workflows/ci-plugin-smoke.yml Plugin smoke (Docker stack)
workflows/ci-plugin-functional.yml Plugin functional tests
workflows/ci-plugin-auth.yml Plugin auth tests

Callable workflows (ci-*, ci-plugin-*) are triggered only via workflow_call from ci.yml, not directly on push.

Plugin integration jobs

Three callable workflows exercise the live Weblate Docker stack (docker/docker-compose.ci.yml). Each job builds the image, runs compose up -d --wait, probes /healthz/ and the Boost ping endpoint, creates an API token (with retry), then runs pytest with pytest-timeout and one rerun on failure.

Job Workflow Typical duration Hard limit (timeout-minutes) Notes
Plugin smoke ci-plugin-smoke.yml ~8–12 min 15 Stack image build dominates
Plugin functional ci-plugin-functional.yml ~15–22 min 25 GitHub E2E needs repository secret
Plugin auth ci-plugin-auth.yml ~8–12 min 10 Auth + rate-limit tests

Secrets and environment

Variable Where Purpose
GH_TEST_REPO_TOKEN Repository secret (functional job only) Classic PAT with repo scope for ephemeral GitHub repos in tests/plugin/test_functional.py. If unset, GitHub/Celery E2E tests are skipped.
HEALTH_TIMEOUT CI workflow env / shell default Seconds to wait for /healthz/ after compose --wait. Defaults: smoke/auth 240, functional 300.
PYTEST_PLUGIN_OPTS Optional override in entrypoint scripts Default includes --timeout, --timeout-method=thread, --reruns 1, --reruns-delay 5. Smoke/auth use --timeout=120; functional uses --timeout=300.
WEBLATE_PORT Optional Host port for Weblate (default 8080).

Local reproduction

bash scripts/plugin-smoke.sh
bash scripts/plugin-auth.sh
GH_TEST_REPO_TOKEN=<classic PAT with repo> bash scripts/plugin-functional.sh

Skip slow plugin tests during local iteration: add -m "not slow" to the pytest invocation in the script, or set PYTEST_PLUGIN_OPTS accordingly.

Other paths

Path Role
ci/apt-install Apt packages for Weblate-related CI jobs

Deploy environments and secrets

cd.yml selects the GitHub environment from the CI branch (workflow_run.head_branch):

Environment CI branch When deploy runs
staging develop After a successful CI run on a push to develop
production main After a successful CI run on a push to main (typically following promote-main.yml)

Both environments use the same secret names (configure different values per host):

Secret Purpose
SSH_HOST Deploy server hostname
SSH_USER SSH user
SSH_PRIVATE_KEY Private key for deploy
WEBLATE_PORT Host port for post-deploy /healthz/ poll
WEBLATE_URL_PREFIX URL prefix for health check (e.g. /weblate)
SSH_PORT Optional SSH port (default 22)

Server path: /opt/cppa-weblate-plugin with docker/docker-compose.cd.yml. Full procedure: docs/deployment-runbook.md.

Production promotion (repository secret)

promote-main.yml is separate from deploy: it ff-only merges develop into main and pushes with PROMOTE_PAT (classic or fine-grained PAT, Contents: write). Without a PAT, GitHub does not trigger CI or cd.yml on that push. Optional: required reviewers on the production environment only.

Weblate version pinning

Weblate is not bumped by Dependabot. A single logical release is pinned in two places:

Location Example Format
pyproject.toml Weblate[all]==2026.5 PyPI calver
docker/Dockerfile.weblate-plugin FROM weblate/weblate:2026.5.0.0 Docker fixed tag YEAR.MONTH.PATCH.BUILD

Mapping lives in scripts/weblate-version-map.sh. CI runs scripts/check-weblate-pin-sync.sh on every PR. weblate-pin-bump.yml opens a PR weekly (Monday 09:00 UTC) when a newer PyPI release has a matching Docker fixed tag.