gh-action-workflows

Reusable GitHub Actions workflows for CI/CD pipelines at ZeitOnline.

The workflows provided here are intended for two main purposes, (continuously) deploying projects and creating releases for them as well as building and deploying so called "nightwatch" tests that are meant to help with monitoring the health/status of said projects.

The first use-case uses a number of them as building bricks and for a project-specific CI/CD workflow that typically looks like this:

name: Backend CI
on:
  workflow_dispatch:
  push:
    branches:
      - 'main'
concurrency:
  group: backend
  cancel-in-progress: true
jobs:
  linter:
    uses: zeitonline/gh-action-workflows/.github/workflows/lefthook.yaml
  k8s:
    uses: zeitonline/gh-action-workflows/.github/workflows/k8s-validation.yaml
  # run 'release-please' first
  release-please:
    needs: [linter, k8s]
    uses: zeitonline/gh-action-workflows/.github/workflows/release-please.yaml
    secrets: inherit
  # without release: build new images for 'staging'
  build:
    needs: release-please
    if: ${{ ! needs.release-please.outputs.release_created }}
    uses: zeitonline/gh-action-workflows/.github/workflows/build-test-push.yaml
    secrets: inherit
    with:
      targets: postgrest migrator
      versions: k8s/staging/versions
  # with release: promote images to 'production' and notify
  promote-images:
    needs: release-please
    if: needs.release-please.outputs.release_created
    uses: zeitonline/gh-action-workflows/.github/workflows/add-tag.yaml
    secrets: inherit
    with:
      tag: ${{ needs.release-please.outputs.tag_name }}
  notify:
    needs: release-please
    if: needs.release-please.outputs.release_created
    uses: zeitonline/gh-action-workflows/.github/workflows/release-notification.yaml
    secrets: inherit
    with:
      environment: production
      version: ${{ needs.release-please.outputs.tag_name }}
      emoji: tada

The second just uses nightwatch-build to build, test and push updated "nightwatch" images. It is typically used like this:

name: Build nightwatch tests
on:
  workflow_dispatch:
  push:
    paths:
      - 'smoketest/**'
jobs:
  build:
    uses: zeitonline/gh-action-workflows/.github/workflows/nightwatch-build.yaml
    secrets: inherit
    with:
      versions: k8s/base/nightwatch/versions
      gke_cluster: main-staging-25-01

• build-test-push — Build, test and push Docker images for staging deployments
• add-tag — Re-tag existing images in the registry for production deployments
• release-please — Manage releases via Release Please
• commit-lint — Lint commit messages using commitlint
• lefthook — Run pre-commit code checks via Lefthook
• pre-commit — Run code checks via pre-commit
• k8s-validation — Validate Kubernetes manifests using kubeval
• k8s-tests — Run the pytest-based assertions over the generated Kubernetes manifests
• k8s-policy-tests — Run the generic zeit.k8stesting policy suite without any project-side test files
• nightwatch-build — Build, push and run Nightwatch smoke test images
• release-notification — Notify Slack and Prometheus about deployments

Runs tests inside Docker Compose, publishes test results, then builds each target, scans it with the Sysdig CLI scanner (policy sysdig-best-practices) and pushes the resulting multi-target Docker images to Google Artifact Registry. When a versions directory is provided, it also updates the Kustomize image tags and commits them back — intended for automatic staging deployments.

Adds an additional tag (typically the release version) to images that already exist in Google Artifact Registry. This enables production deployments by re-using the exact same images that were previously built and tested for staging — without rebuilding them.

Before tagging, it checks that the images were built from the commit preceding the release (apart from changes to the versions directory itself). Otherwise, e.g. when the release pull request was merged before the 'staging' build had finished, the workflow fails instead of promoting outdated images.

Runs Release Please to manage versioned releases via conventional commits. Can be used both as a reusable workflow (via workflow_call) and standalone (triggered on push to main or via workflow_dispatch to create releases for this repo itself). Outputs whether a release was created and the tag name, so callers can decide between a staging build or a production re-tag.

Validates commit messages against conventional commit rules using commitlint.

Runs code quality checks using Lefthook (as a replacement for the pre-commit workflow below). Sets up uv and optionally Python and/or Node.js, then executes lefthook run pre-commit --all-files.

Runs pre-commit hooks via uvx. Optionally sets up Python and/or Node.js runtimes for hooks that need them.

Validates Kubernetes manifests by running kubectl kustomize for each environment and checking the output with kubeval.

Runs the pytest-based test suite that makes assertions about the generated Kubernetes manifests (rendered via kustomize). The suite lives in its own directory with its own pyproject.toml and typically builds on the zeit.k8stesting plugin, which contributes the shared policy tests. This complements k8s-validation (schema validation): validation checks that the manifests are valid, these tests check that they are correct for our conventions (variant -pgXX suffixes, placeholder replacement, PGSERVICE routing, …).

jobs:
  k8s-tests:
    uses: zeitonline/gh-action-workflows/.github/workflows/k8s-tests.yaml
    with:
      project: premium-services

Runs the generic zeit.k8stesting policy suite against a project's rendered manifests without any project-side test files. The job materialises an ephemeral k8s/tests/ from the inputs below and runs it — ideal for the many simple projects that only need the shared policy (A1–A8) and no custom kustomize_jq tests. Projects that do need custom assertions keep their own suite and use k8s-tests instead (this workflow fails fast if a k8s/tests/ already exists).

The inputs mirror zeit.k8stesting's K8sPolicy. Default posture: universal checks on, variant-versioning off — placeholder-leaks (A1), explicit replicas (A6) and readiness probes (A7) run; the -pgXX variant-versioning check (A2) is off by default; A3/A4/A5/A8 are opt-in (enabled by providing their inputs).

jobs:
  k8s-policy:
    uses: zeitonline/gh-action-workflows/.github/workflows/k8s-policy-tests.yaml
    secrets: inherit
    with:
      project: my-service
      environments: "staging production"

Builds a Docker image containing per project "smoke" or "nightwatch" tests, pushes it to GAR, runs a security scan (on PRs), and executes the tests in a Kubernetes pod created via kustomize. On main, it updates the image tag in Kustomize and commits it back.

Posts a deployment notification to Slack (via Hackbot) and pushes a deployment timestamp metric to Prometheus (via pushgateway). Both halves are optional: setting emoji to an empty string skips the Slack notification, setting prometheus_job to an empty string skips the metric.