CI/CD Workflows¶
GitHub Actions pipelines that gate pull requests, scan for
vulnerabilities, and promote artefacts through dev → stage →
main (tagged) environments.
Related:
- CI/CD Pipeline — architecture overview
- Release Management — versioning & promotion
- Workflow Guide — developer day-to-day
Pipeline Flow¶
flowchart LR
PR[Pull Request] --> Q[Quality Checks]
PR --> T[Tests]
PR --> S[Security]
PR -->|frontend diff| L[Lighthouse]
Q --> R[Review]
T --> R
S --> R
L --> R
R --> Mdev[Merge to dev]
Mdev --> Ddev[Deploy dev]
Ddev --> PRstage[Open dev → stage PR]
PRstage --> Mstage[Merge to stage]
Mstage --> Dstage[Deploy stage]
Dstage --> PRmain[Open stage → main PR]
PRmain --> Mmain[Merge to main]
Mmain --> Tag[Tag from package.json]
Tag --> Release[GitHub Release]
Tag --> Dprod[Deploy prod + Helm chart]
Cron[Weekly cron · Sun 03:00 UTC] --> Scan[Image vulnerability scan]
classDef ci fill:#e1f5ff,stroke:#0288d1
classDef deploy fill:#e8f5e9,stroke:#2e7d32
classDef release fill:#fff4e1,stroke:#ef6c00
classDef cron fill:#f3e5f5,stroke:#6a1b9a
class Q,T,S,L ci
class Ddev,Dstage,Dprod deploy
class CL,Tag,Release release
class Cron,Scan cron
The Cron → Scan branch runs independently of the deploy chain
(scheduled trigger only); it is drawn separately to avoid implying
production deploys cause the scan.
Workflows¶
The repository ships twelve workflows under .github/workflows/.
quality-check.yml — Quality Checks¶
Trigger: PR / push to main, dev, stage, ci-test/**.
Jobs: frontent-quality runs make lint then tsc/vue-tsc;
backend-quality runs make lint (Ruff + Prettier) followed by a
separate make type-check step (mypy). Both jobs run in parallel;
failure blocks merge.
test.yml — Tests¶
Trigger: PR / push to main, dev, stage, ci-test/**.
Jobs: test-backend (pytest + Codecov), test-frontend (Vitest +
Codecov). Coverage uploads target the same Codecov project; tokens
are required only for private forks.
integration-tests.yml — Backend Integration Tests¶
Trigger: daily cron (03:30 UTC), workflow_dispatch, push to
ci-test/**. Job: test-backend-integration runs
make test-cov-xml-integration and uploads the report to Codecov
under the backend-integration flag.
security.yml — Security Checks¶
Trigger: PR to main/dev/stage, push to main, weekly cron
(Mon 00:00 UTC). Jobs: npm-audit (root + frontend),
python-security (uv audit + Bandit), codeql (JavaScript +
Python matrix), secrets-scan (TruffleHog).
lighthouse.yml — Lighthouse CI (daily)¶
Trigger: daily cron (04:00 UTC), workflow_dispatch, push to
ci-test/**. Job: lighthouse audits all 24 routes via
frontend/.lighthouserc.json (single source of truth, shared with
make lighthouse). The build injects
window.__LIGHTHOUSE_BYPASS__ = true into the served index.html
so navigation guards skip auth in CI; the flag never reaches
production builds. The full sweep runs nightly off the PR critical
path; reproduce locally with make lighthouse.
App deploy (gitlab.epfl.ch)¶
No GitHub workflow deploys the app. quay-its.epfl.ch only accepts
traffic from the EPFL network, so dev, stage and tags vX.Y.Z
deploy from .gitlab-ci.yml on gitlab.epfl.ch, through the
EPFL-ENAC/build-push-deploy component
(plan 2909).
APP_VERSION is computed by scripts/app-version.sh inside each build
job, from the root package.json and the commit date. Images whose build context did not change since the
last dev image are re-tagged instead of rebuilt (reuse_unchanged_images;
a root package.json change rebuilds all three); a reused pod keeps the
APP_VERSION of the commit that last changed its component. The component
packages and pushes the Helm chart in parallel with the image builds.
The overlay update waits for the chart. Images go to both
ghcr.io and the EPFL Quay registry quay-its.epfl.ch (path
svc1751); manifests update Argo CD repos
EPFL-ENAC/enack8s-app-config and
EPFL-ENAC/openshift-app-config respectively. Tags promote to
production and publish chart X.Y.Z. Branches map to the matching
environment URL.
mirror-to-gitlab.yml — Mirror to GitLab¶
Trigger: push to dev, stage, or tags v*.*.*. Pushes the ref
to gitlab.epfl.ch, which cannot pull from GitHub. A tag goes as a tag.
deploy-storybook.yml — Storybook Image + Manifest Dispatch¶
Trigger: push to dev, main, stage, or the storybook
feature branch. Job: build-and-push builds the Storybook
container from frontend/Dockerfile.storybook, pushes it to
ghcr.io/epfl-enac/co2-calculator-storybook, then POSTs a
repository_dispatch (event_type: update-manifest) to
EPFL-ENAC/enack8s-app-config so Argo CD picks up the new image.
It does not publish a static Storybook site — the artifact is the
container image plus the dispatch event.
deploy-pages.yml: Docs (GitHub Pages)¶
Trigger: a vX.Y.Z tag, or by hand with a tag. The workflow waits
until GitLab pushes the docs image of that tag to GHCR. Then it copies
the site out of the image and publishes it to GitHub Pages. Pages and
prod serve the same files. Each environment serves its own docs at
/docs, from the GitLab deploy. The Docs Build job of
quality-check.yml builds the docs on every pull request.
release-please.yml — Tag and Release¶
Trigger: PR closed against main. Job: release runs
only when the merged PR came from stage. Despite the workflow
filename, it does not invoke the release-please action: it
reads the version from package.json, creates an annotated git
tag v<version> directly, takes the top CHANGELOG.md entry
(written by hand on dev; the job fails if it is not for that
version), and publishes it as a GitHub Release via
softprops/action-gh-release. See
Release Management for the full
promotion flow.
image-vulnerability-scan.yml — Registry Vulnerability Scan¶
Trigger: weekly cron (Sun 03:00 UTC) + workflow_dispatch.
Job: scan-images pulls published container images and runs a
vulnerability scan, opening issues for newly discovered CVEs.
Release Management¶
Versioning, environment promotion (dev → stage → main), and
hotfix procedure live in
Release Management. The
release-please.yml workflow is the automation entry point for
that flow.
Required Secrets¶
| Secret | Used by | Notes |
|---|---|---|
GITHUB_TOKEN |
all | auto-provided |
MY_RELEASE_PLEASE_TOKEN |
release-please.yml |
PAT with contents: write to push tags + create releases |
CD_TOKEN |
deploy-storybook.yml |
EPFL-ENAC build-push-deploy action token; also the bearer token for the Storybook repository_dispatch POST to EPFL-ENAC/enack8s-app-config |
GITLAB_DEPLOY_KEY |
mirror-to-gitlab.yml |
private SSH key of the GitLab deploy key with write access |
CODECOV_TOKEN |
test.yml, integration-tests.yml |
optional, required for private forks |
Status Badges¶
[](https://github.com/EPFL-ENAC/co2-calculator/actions/workflows/quality-check.yml)
[](https://github.com/EPFL-ENAC/co2-calculator/actions/workflows/test.yml)
[](https://github.com/EPFL-ENAC/co2-calculator/actions/workflows/security.yml)
Local Pre-flight¶
Reproduce CI locally before pushing:
make lint # quality-check.yml
make test # test.yml
make ci # full simulation
Troubleshooting¶
- CodeQL fails on Python: confirm
language: [javascript, python]matrix and thatpyproject.tomlis detected. - Lighthouse times out: raise the per-run budget in
frontend/.lighthouserc.jsonor trim the URL list. - Deploy step missing chart version: check the action's
publish-chartjob;update-manifesttakes the version from its output, and a failed chart render or push skips the manifest update. - Tag not created on main merge:
release-please.ymlonly fires when the merged PR's head ref isstage; merges from any other branch are skipped by design. The tag name comes frompackage.json— bump it on thestagebranch before merging.
Enable verbose logs by setting repo secrets
ACTIONS_RUNNER_DEBUG=true and ACTIONS_STEP_DEBUG=true.