docker.yml

name: Build, Scan & Publish Docker Images

on:
  # CI calls this reusable workflow only after its aggregate gate succeeds.
  # Keeping publication in the same trusted main run avoids workflow_run's
  # privileged-trigger boundary while preserving the all-tests-first gate.
  workflow_call:

concurrency:
  group: docker-release
  # Let a release finish coherently. Cancelling during publication must never
  # interrupt the final complete-release pointer update.
  cancel-in-progress: false

env:
  REGISTRY: ghcr.io
  IMAGE_PREFIX: ghcr.io/openmapx
  # Distinguish security refreshes and retries of the same source commit.
  RELEASE_ID: ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}

permissions:
  contents: read

jobs:
  gate:
    name: Verify current trusted main commit
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
    outputs:
      sha: ${{ steps.verify.outputs.sha }}
    steps:
      - name: Require the current trusted main commit
        id: verify
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            if (!["push", "schedule"].includes(context.eventName) || context.ref !== "refs/heads/main") {
              core.setFailed("Refusing a release outside a trusted main push or scheduled run");
              return;
            }

            const candidate = context.sha;
            const { data: main } = await github.rest.git.getRef({
              ...context.repo,
              ref: "heads/main",
            });
            if (candidate !== main.object.sha) {
              core.setFailed(
                `Candidate ${candidate} is not the current main commit ${main.object.sha}`,
              );
              return;
            }

            core.setOutput("sha", candidate);

  plan:
    name: Select changed images from the published release
    needs: gate
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      packages: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.gate.outputs.sha }}
          persist-credentials: false
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: .nvmrc
      - name: Log in to read the previous complete release
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ github.token }}
      - name: Compare build inputs with the last published release
        env:
          RELEASE_SHA: ${{ needs.gate.outputs.sha }}
          FORCE_REBUILD: ${{ github.event_name == 'schedule' || vars.OPENMAPX_FORCE_IMAGE_REBUILD == 'true' }}
        run: node scripts/docker-release-plan.mjs plan release-plan
      - name: Preserve the complete build selection
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: docker-release-plan-${{ github.run_id }}-${{ github.run_attempt }}
          path: release-plan/release-plan.json
          if-no-files-found: error
          retention-days: 1

  build:
    name: Build or reuse and scan ${{ matrix.app }}
    needs: [gate, plan]
    runs-on: ubuntu-latest
    timeout-minutes: 60
    permissions:
      contents: read
      packages: write
      security-events: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - app: api
            context: .
            dockerfile: apps/api/Dockerfile
          - app: web
            context: .
            dockerfile: apps/web/Dockerfile
          - app: data-manager
            context: .
            dockerfile: services/data-manager/Dockerfile
          - app: ops-agent
            context: .
            dockerfile: apps/ops-agent/Dockerfile
          - app: privacy-backup
            context: .
            dockerfile: services/ops-agent/privacy-backup/Dockerfile
          - app: transitous-runner
            context: .
            dockerfile: apps/transitous-runner/Dockerfile
          - app: transitous-tools
            context: services/motis/tools/transitous
            dockerfile: services/motis/tools/transitous/Dockerfile

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.gate.outputs.sha }}
          persist-credentials: false

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: .nvmrc
          package-manager-cache: false
      - name: Download the complete build selection
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: docker-release-plan-${{ github.run_id }}-${{ github.run_attempt }}
          # Keep CI artifacts outside Docker build contexts.
          path: ${{ runner.temp }}/release-plan
      - name: Select build or reuse for this image
        id: selection
        env:
          APP: ${{ matrix.app }}
          RELEASE_SHA: ${{ needs.gate.outputs.sha }}
        run: node scripts/docker-release-plan.mjs select "$APP" "$RUNNER_TEMP/release-plan/release-plan.json"

      # Buildx startup pulls its BuildKit image from Docker Hub. Retry that
      # infrastructure fetch once, but never soften build or scan failures.
      - name: Set up Docker Buildx
        if: steps.selection.outputs.rebuild == 'true'
        id: buildx
        continue-on-error: true
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      - name: Retry Docker Buildx setup
        if: steps.buildx.outcome == 'failure'
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      - name: Log in to the candidate registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ github.token }}

      # Push content-addressed candidate blobs only. No SHA or latest tag is
      # visible until all matrix legs have passed the mandatory scan below.
      - name: Build untagged candidate by digest
        if: steps.selection.outputs.rebuild == 'true'
        id: build
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: ${{ matrix.context }}
          file: ${{ matrix.dockerfile }}
          platforms: linux/amd64
          pull: true
          no-cache: ${{ steps.selection.outputs.refresh == 'true' }}
          build-args: ${{ matrix.app == 'web' && format('SW_BUILD_ID={0}', needs.gate.outputs.sha) || '' }}
          outputs: type=image,name=${{ env.IMAGE_PREFIX }}/${{ matrix.app }},push-by-digest=true,name-canonical=true,push=true
          labels: |
            org.opencontainers.image.revision=${{ needs.gate.outputs.sha }}
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
          cache-from: type=gha,scope=${{ matrix.app }}
          cache-to: type=gha,mode=max,scope=${{ matrix.app }}
          provenance: mode=max
          sbom: true

      - name: Select the exact digest to scan
        id: candidate
        env:
          REBUILD: ${{ steps.selection.outputs.rebuild }}
          BUILT_DIGEST: ${{ steps.build.outputs.digest }}
          REUSED_DIGEST: ${{ steps.selection.outputs.digest }}
        run: |
          if [ "$REBUILD" = true ]; then
            DIGEST="$BUILT_DIGEST"
          else
            DIGEST="$REUSED_DIGEST"
          fi
          if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "Invalid candidate image digest" >&2
            exit 1
          fi
          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"

      # Keep the complete finding set for review, including vulnerabilities
      # for which the distro or upstream project has not published a fix.
      - name: Audit exact candidate digest with Trivy
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ env.IMAGE_PREFIX }}/${{ matrix.app }}@${{ steps.candidate.outputs.digest }}
          format: sarif
          output: trivy-${{ matrix.app }}.sarif
          scanners: vuln
          vuln-type: os,library
          severity: CRITICAL,HIGH
          limit-severities-for-sarif: true
          ignore-unfixed: "false"
          exit-code: "0"

      # This is the promotion policy, not merely reporting: any actionable
      # HIGH/CRITICAL OS or library vulnerability blocks every image tag.
      # Unfixed advisories stay visible in the SARIF audit above, but cannot
      # permanently deadlock releases when no remediation exists.
      - name: Gate exact candidate digest with Trivy
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ env.IMAGE_PREFIX }}/${{ matrix.app }}@${{ steps.candidate.outputs.digest }}
          format: table
          scanners: vuln
          vuln-type: os,library
          severity: CRITICAL,HIGH
          ignore-unfixed: "true"
          trivyignores: .trivyignore.yaml
          exit-code: "1"

      # Code-scanning upload needs GHAS in private repositories. Reporting may
      # be unavailable, but both scans above are unconditional and the
      # actionable-finding gate is fail-closed.
      - name: Upload Trivy results
        if: always() && (github.event.repository.visibility == 'public' || vars.ENABLE_CODE_SCANNING == 'true')
        uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
        with:
          sarif_file: trivy-${{ matrix.app }}.sarif
          category: trivy-${{ matrix.app }}

      - name: Export approved digest
        env:
          DIGEST: ${{ steps.candidate.outputs.digest }}
        run: |
          if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "Invalid image digest: $DIGEST" >&2
            exit 1
          fi
          mkdir -p digest
          touch "digest/${DIGEST#sha256:}"

      - name: Preserve approved digest for aggregate promotion
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: docker-digest-${{ matrix.app }}-${{ github.run_id }}-${{ github.run_attempt }}
          path: digest/*
          if-no-files-found: error
          retention-days: 1

  validate-privacy-release:
    name: Validate privacy release evidence
    needs: gate
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.gate.outputs.sha }}
          persist-credentials: false

      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: .nvmrc
          cache: pnpm

      - run: pnpm install --frozen-lockfile

      - name: Install docs dependencies for policy validation
        run: pnpm --dir docs install --frozen-lockfile

      - name: Validate the exact release checkout
        run: pnpm validate:privacy-release "$RUNNER_TEMP/privacy-release-validation.json"

      - name: Preserve exact-checkout privacy validation evidence
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: privacy-release-validation-${{ needs.gate.outputs.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ runner.temp }}/privacy-release-validation.json
          if-no-files-found: error
          retention-days: 1

  promote:
    name: Publish coherent release
    needs: [gate, plan, build, validate-privacy-release]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      packages: write
    steps:
      - name: Download the complete build selection
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: docker-release-plan-${{ github.run_id }}-${{ github.run_attempt }}
          path: release-plan
      - name: Download every approved digest
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          pattern: docker-digest-*-${{ github.run_id }}-${{ github.run_attempt }}
          path: digests

      - name: Download exact-checkout privacy validation evidence
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: privacy-release-validation-${{ needs.gate.outputs.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
          path: privacy-release-validation

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      - name: Log in for promotion
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ github.token }}

      # Run-qualified tags preserve each release; SHA tags remain convenience aliases.
      # The release-manifest pointer below is the atomic release-selection contract.
      - name: Promote every scanned digest to SHA and assemble the release manifest
        env:
          IMAGE_PREFIX: ${{ env.IMAGE_PREFIX }}
          RELEASE_MANIFEST_IMAGE: ${{ env.IMAGE_PREFIX }}/release-manifest
          RELEASE_SHA: ${{ needs.gate.outputs.sha }}
        run: |
          mkdir -p release-manifest
          privacy_evidence=privacy-release-validation/privacy-release-validation.json
          if [ ! -f "$privacy_evidence" ]; then
            echo "Exact-checkout privacy validation evidence is missing" >&2
            exit 1
          fi
          node --input-type=module <<'NODE'
          import { readFileSync } from "node:fs";
          const evidence = JSON.parse(
            readFileSync("privacy-release-validation/privacy-release-validation.json", "utf8"),
          );
          const exactKeys = (value, keys) =>
            value &&
            typeof value === "object" &&
            !Array.isArray(value) &&
            JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
          if (
            !exactKeys(evidence, ["version", "sourceBuildFingerprint", "validatedAt", "checks"]) ||
            evidence.version !== 1 ||
            !/^[a-f0-9]{64}$/.test(evidence.sourceBuildFingerprint) ||
            typeof evidence.validatedAt !== "string" ||
            !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(evidence.validatedAt) ||
            new Date(evidence.validatedAt).toISOString() !== evidence.validatedAt ||
            !exactKeys(evidence.checks, [
              "translationsConsistent",
              "openApiConsistent",
              "policyConsistent",
            ]) ||
            evidence.checks.translationsConsistent !== true ||
            evidence.checks.openApiConsistent !== true ||
            evidence.checks.policyConsistent !== true
          ) {
            throw new Error("Exact-checkout privacy validation evidence is invalid");
          }
          NODE
          first=true
          image_lines=""
          for app in api web data-manager ops-agent privacy-backup transitous-runner transitous-tools; do
            shopt -s nullglob
            digest_files=("digests/docker-digest-${app}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"/*)
            if [ "${#digest_files[@]}" -ne 1 ] || [ ! -f "${digest_files[0]}" ]; then
              echo "Expected exactly one approved digest artifact for ${app}" >&2
              exit 1
            fi
            digest_file="${digest_files[0]}"
            DIGEST="sha256:${digest_file##*/}"
            if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
              echo "Invalid approved digest for ${app}: $DIGEST" >&2
              exit 1
            fi

            IMAGE="${IMAGE_PREFIX}/${app}"
            docker buildx imagetools create \
              --prefer-index=false \
              --tag "${IMAGE}:${RELEASE_SHA}" \
              --tag "${IMAGE}:${RELEASE_ID}" \
              "${IMAGE}@${DIGEST}"
            docker buildx imagetools inspect "${IMAGE}:${RELEASE_SHA}"

            if [ "$first" = true ]; then
              first=false
            else
              image_lines="${image_lines},\n"
            fi
            image_lines="${image_lines}    \"${app}\": \"${IMAGE}@${DIGEST}\""
          done

          {
            printf '{\n'
            printf '  "schemaVersion": 1,\n'
            printf '  "release": "%s",\n' "$RELEASE_ID"
            printf '  "images": {\n'
            printf '%b\n' "$image_lines"
            printf '  },\n'
            printf '  "privacyReleaseValidation": '
            cat privacy-release-validation/privacy-release-validation.json
            printf '}\n'
          } > release-manifest/release-manifest.json

          node --input-type=module <<'NODE'
          import { readFileSync, writeFileSync } from "node:fs";
          const path = "release-manifest/release-manifest.json";
          const manifest = JSON.parse(readFileSync(path, "utf8"));
          const plan = JSON.parse(readFileSync("release-plan/release-plan.json", "utf8"));
          if (plan.version !== 1 || plan.release !== manifest.release || plan.sourceRevision !== process.env.RELEASE_SHA ||
              plan.privacyFingerprint !== manifest.privacyReleaseValidation.sourceBuildFingerprint ||
              plan.buildMetadata?.version !== 1) {
            throw new Error("Release plan does not match the validated release");
          }
          for (const app of Object.keys(manifest.images)) {
            const selected = plan.images.find((image) => image.app === app);
            const metadata = plan.buildMetadata.images[app];
            if (!selected || !metadata ||
                (!selected.rebuild && manifest.images[app] !== `${process.env.IMAGE_PREFIX}/${app}@${selected.digest}`)) {
              throw new Error(`Approved digest does not match the release plan for ${app}`);
            }
          }
          manifest.buildMetadata = plan.buildMetadata;
          writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`);
          NODE

          cat > release-manifest/Dockerfile <<'EOF'
          FROM scratch
          COPY release-manifest.json /release-manifest.json
          EOF

      - name: Publish the immutable release manifest
        env:
          RELEASE_MANIFEST_IMAGE: ${{ env.IMAGE_PREFIX }}/release-manifest
          RELEASE_SHA: ${{ needs.gate.outputs.sha }}
        run: |
          docker buildx build \
            --file release-manifest/Dockerfile \
            --tag "${RELEASE_MANIFEST_IMAGE}:${RELEASE_SHA}" \
            --tag "${RELEASE_MANIFEST_IMAGE}:${RELEASE_ID}" \
            --push \
            release-manifest
          docker buildx imagetools inspect "${RELEASE_MANIFEST_IMAGE}:${RELEASE_ID}"

      # Maintain the manifest-tag fallback only from a complete, scanned set.
      # These aliases move independently; production uses the release pointer.
      # Retag directly so existing consumers never hit a delete/recreate gap.
      - name: Advance and verify application latest aliases
        env:
          IMAGE_PREFIX: ${{ env.IMAGE_PREFIX }}
        run: |
          for app in api web data-manager ops-agent privacy-backup transitous-runner transitous-tools; do
            shopt -s nullglob
            digest_files=("digests/docker-digest-${app}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"/*)
            if [ "${#digest_files[@]}" -ne 1 ] || [ ! -f "${digest_files[0]}" ]; then
              echo "Expected exactly one approved digest artifact for ${app}" >&2
              exit 1
            fi
            digest_file="${digest_files[0]}"
            DIGEST="sha256:${digest_file##*/}"
            if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
              echo "Invalid approved digest for ${app}: $DIGEST" >&2
              exit 1
            fi

            IMAGE="${IMAGE_PREFIX}/${app}"
            docker buildx imagetools create \
              --prefer-index=false \
              --tag "${IMAGE}:latest" \
              "${IMAGE}@${DIGEST}"
            published_digest=$(docker buildx imagetools inspect "${IMAGE}:latest" --format '{{.Manifest.Digest}}')
            if [ "$published_digest" != "$DIGEST" ]; then
              echo "Published digest mismatch for ${IMAGE}:latest: expected ${DIGEST}, got ${published_digest}" >&2
              exit 1
            fi
          done

      # This one registry tag is the atomic release-selection switch. If building,
      # scanning, any SHA promotion, publishing the immutable manifest, or
      # updating/verifying an application alias fails, it retains the prior release.
      - name: Advance the complete release pointer
        env:
          RELEASE_MANIFEST_IMAGE: ${{ env.IMAGE_PREFIX }}/release-manifest
          RELEASE_SHA: ${{ needs.gate.outputs.sha }}
        run: |
          docker buildx imagetools create \
            --tag "${RELEASE_MANIFEST_IMAGE}:latest" \
            "${RELEASE_MANIFEST_IMAGE}:${RELEASE_ID}"
          docker buildx imagetools inspect "${RELEASE_MANIFEST_IMAGE}:latest"