CI/CD and release automation¶

This page documents the GitHub Actions workflows for the ecmwf-sites repository and the Makefile targets they rely on. The helper tests that protect these workflows are inventoried in 20-testing.

flowchart LR
    PR["pull request / push"] --> CI["CI workflow (make test)"]
    SEC["Security workflow (advisory: CodeQL, audits, zizmor, helper tests)"] -. "parallel, advisory" .- CI
    CI -- "push to develop + CI green" --> DEV["Develop: gate + publish develop images + pre-release chart"]
    MAIN["main, workflow_dispatch"] --> REL["Release: gate + tests + tag + GitHub release"]
    REL --> PUB["Publish: images + chart (tag)"]
    PUB --> DOCS["Publish docs (sitesctl upload)"]

Design goals¶

The repository keeps workflow logic simple by:

• putting reusable execution logic in the root Makefile
• keeping workflow YAML focused on triggers, permissions, and credentials
• using pinned third-party actions
• validating workflow syntax with actionlint and security patterns with zizmor
• checking out code without a persisted token (persist-credentials: false, except the release tag job, which authenticates with a deploy key instead of a token)
• passing workflow values to run: steps through environment variables, not inline ${{ }} expressions
• avoiding pull_request_target
• gating fork pull request execution with approved-for-ci
• writing a concise job summary for every job that starts

Workflow map¶

The shared build entrypoints are in Makefile entrypoints, the documentation pipeline in Documentation site, and the local run recipes in Local testing.

Runner images¶

Jobs that use GitHub-hosted runners pin the ubuntu-24.04 label. This keeps production workflows independent of changes to the ubuntu-latest label. runner-compatibility.yml runs the repository test suite on both ubuntu-24.04 and ubuntu-26.04 on a schedule and by manual dispatch. It has read-only permissions and does not publish anything.

The image publishing jobs use the managed arc-dind-pet-vsphere-prod runner in the pet-privileged-runners group. The ubuntu-24.04 pinning rule applies to hosted-runner jobs only. .github/actionlint.yaml lists the self-hosted label plus ubuntu-26.04 as valid runner labels.

Job summaries¶

The local ./.github/actions/write-job-summary action writes Markdown to GITHUB_STEP_SUMMARY. Each summary includes the job status, workflow, job, event, ref, commit, workflow-run link, and job-specific details. Summary steps use always() so a failed check still reports its result.

Security scan helpers also append their findings to the same job summary. They keep the detailed scan result, while the shared action provides the common workflow context.

GitHub does not run steps in a job that is skipped by a job-level condition, so skipped jobs have no job summary. A reusable workflow caller has no steps of its own; its called workflow writes the summaries for the jobs that run.

Secrets and registry access¶

All Sites container images are stored in the ECMWF container registry (ECCR):

• registry: eccr.ecmwf.int
• repository prefix: eccr.ecmwf.int/sites-oss
• Helm chart: oci://eccr.ecmwf.int/sites-oss/ecmwf-sites

This is the only registry for Sites images. The workflows, the Makefile, the Dockerfiles, and the Helm chart use it on purpose. Do not replace or remove eccr.ecmwf.int, also when an open-source audit reports it as an internal hostname.

The workflows log in to the registry host eccr.ecmwf.int. The Makefile uses sites-oss as the default project for image names and chart publication; SITES_PRIVATE_REGISTRY and SITES_PRIVATE_REGISTRY_PROJECT can override it.

The publishing workflows require:

• ECCR_USERNAME
• ECCR_PASSWORD

These credentials are only used in workflows that push images.

./.github/actions/prepare-credentials resolves each value in order: repository secret, then Vault. The workflows never read these credentials from repository variables. Vault is not configured for Sites at the moment: the role and the secret path in the action are placeholders, and a TODO in the action lists the steps to configure them. The Vault login uses GitHub OpenID Connect (OIDC) authentication (the job needs id-token: write). Two action inputs control it: vault_url (default https://secrets-test.ecmwf.int) and vault_role (default sites-publisher). The action validates and masks the resolved values and exposes them as outputs; the workflows pass them directly to the Docker and Helm login steps and never export them to the job environment. node --test .github/actions/prepare-credentials/credentials.test.cjs covers the resolution and masking rules.

Pinned tool versions¶

The automation pins the tooling it installs:

Workflow permissions model¶

The workflows are written with explicit least-privilege permissions:

• read-only workflows use contents: read
• the release workflow uses contents: write in the tag-and-release job only, because it creates the tag and the GitHub release
• the CodeQL workflow grants only the permissions required to upload security results

Third-party actions are pinned to immutable commit SHAs rather than mutable version tags.

Where to look when changing workflow behavior¶

When updating the automation model, keep these files in sync:

• .github/workflows/*.yml
• .github/actions/*
• Makefile
• the pages in this directory
• docs/design/16-testing.md
• the root README.md

Behaviour requirements¶