reusable-docker-build.yml

name: Docker Build (Cached)

on:
  workflow_call:
    inputs:
      image-name:
        type: string
        required: true
        description: "Full image name (e.g., ls1intum/hephaestus/webapp)"
      docker-file:
        type: string
        required: false
        default: ""
        description: "Path to Dockerfile (required unless use-buildpacks=true)"
      docker-context:
        type: string
        default: "."
        description: "Docker build context"
      use-buildpacks:
        type: boolean
        required: false
        default: false
        description: |
          If true, build via Paketo Cloud Native Buildpacks using
          spring-boot:build-image instead of a Dockerfile. Used for the application
          server to enable Application CDS — see docs/admin/buildpacks-cds-decision.md.
      maven-module:
        type: string
        required: false
        default: ""
        description: "Directory containing the Spring Boot module when use-buildpacks=true (e.g. server/application)"
      registry:
        type: string
        default: "ghcr.io"
        description: "Container registry"
      tags:
        type: string
        required: false
        description: "Additional tags (one per line)"
      labels:
        type: string
        required: false
        description: "OCI labels"
      build-args:
        type: string
        required: false
        description: "Build arguments"
      single-arch:
        type: boolean
        required: false
        default: false
        description: |
          Build only linux/amd64. Callers set this on pull requests to halve Docker build
          wall-clock + cost (the arm64 native build adds ~7 min and PR images are never deployed
          to production). main + release builds leave this false so release tags and pinned
          digests stay multi-arch.
    outputs:
      manifest-digest:
        description: "Published image digest (a multi-architecture manifest-list digest for main and releases)."
        value: ${{ inputs.single-arch && jobs.build.outputs.manifest-digest || jobs.merge.outputs.manifest-digest }}

jobs:
  build:
    name: Build ${{ matrix.platform }} Docker Image
    outputs:
      manifest-digest: ${{ steps.single-digest.outputs.manifest-digest }}
    strategy:
      fail-fast: true
      matrix: ${{ fromJSON(inputs.single-arch && '{"include":[{"platform":"linux/amd64","runner":"ubuntu-24.04"}]}' || '{"include":[{"platform":"linux/amd64","runner":"ubuntu-24.04"},{"platform":"linux/arm64","runner":"ubuntu-24.04-arm"}]}') }}
    timeout-minutes: 45
    runs-on: ${{ matrix.runner }}
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          persist-credentials: false

      # Note: QEMU is NOT needed because we build natively:
      # - linux/amd64 builds on ubuntu-24.04 (x86_64)
      # - linux/arm64 builds on ubuntu-24.04-arm (aarch64)

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
        with:
          # Use TUM's Docker Hub mirror to avoid rate limits (standard ls1intum approach)
          # See: https://github.com/ls1intum/.github/blob/main/.github/workflows/build-and-push-docker-image.yml
          buildkitd-config-inline: |
            [registry."docker.io"]
              mirrors = ["https://docker-mirror.ase.in.tum.de:8765"]

      - name: Log in to Container Registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ inputs.registry }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Prepare tag configuration
        id: tags
        if: inputs.single-arch
        run: |
          {
            echo "tags<<EOF"
            echo "type=ref,event=branch"
            echo "type=ref,event=pr"
            echo "type=sha,prefix="
            while IFS= read -r line || [[ -n "$line" ]]; do
              line=$(echo "$line" | xargs)
              [ -z "$line" ] && continue
              if [[ "$line" == *"type="* ]]; then
                echo "$line"
              else
                IFS=',' read -ra values <<< "$line"
                for value in "${values[@]}"; do
                  value=$(echo "$value" | xargs)
                  [ -n "$value" ] && echo "type=raw,value=$value"
                done
              fi
            done <<< "${{ inputs.tags }}"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ inputs.registry }}/${{ inputs.image-name }}
          tags: ${{ inputs.single-arch && steps.tags.outputs.tags || '' }}
          labels: ${{ inputs.labels }}

      - name: Prepare platform pair
        id: prep
        run: |
          platform=${{ matrix.platform }}
          echo "platform_pair=${platform//\//-}" >> $GITHUB_OUTPUT
          image="${{ inputs.image-name }}"
          echo "image_name=${image//\//-}" >> $GITHUB_OUTPUT

      # Only main may write the shared registry cache.
      - name: Build and push (Dockerfile)
        id: build
        if: ${{ !inputs.use-buildpacks }}
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        env:
          DOCKER_BUILD_RECORD_UPLOAD: false
        with:
          context: ${{ inputs.docker-context }}
          file: ${{ inputs.docker-file }}
          platforms: ${{ matrix.platform }}
          build-args: ${{ inputs.build-args }}
          labels: ${{ steps.meta.outputs.labels }}
          tags: ${{ inputs.single-arch && steps.meta.outputs.tags || '' }}
          push: ${{ inputs.single-arch }}
          outputs: ${{ !inputs.single-arch && format('type=image,"name={0}/{1}",push-by-digest=true,name-canonical=true,push=true', inputs.registry, inputs.image-name) || '' }}
          cache-from: |
            type=registry,ref=${{ inputs.registry }}/${{ inputs.image-name }}:cache-main-${{ steps.prep.outputs.platform_pair }}
          cache-to: ${{ github.ref == 'refs/heads/main' && format('type=registry,ref={0}/{1}:cache-main-{2},mode=max', inputs.registry, inputs.image-name, steps.prep.outputs.platform_pair) || '' }}

      # Buildpacks path: spring-boot:build-image publishes an OCI image (Application CDS enabled),
      # then we capture the per-arch digest so the merge job builds the multi-arch manifest exactly
      # like the Dockerfile path.
      - name: Set up JDK 21
        if: inputs.use-buildpacks
        uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c # v6.0.0
        with:
          distribution: temurin
          java-version: 21

      - name: Cache Maven dependencies
        if: inputs.use-buildpacks
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.m2/repository
          key: m2-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/pom.xml') }}
          restore-keys: |
            m2-${{ runner.os }}-${{ runner.arch }}-

      # Fail fast if a downstream caller flips use-buildpacks=true without supplying maven-module.
      # `working-directory: ""` would silently run from the repo root, where there is no ./mvnw.
      - name: Validate buildpacks inputs
        if: inputs.use-buildpacks
        run: |
          if [ -z "${{ inputs.maven-module }}" ]; then
            echo "::error::use-buildpacks=true requires maven-module (e.g. server/application)"
            exit 1
          fi

      - name: Build and push (Paketo Buildpacks + CDS)
        id: build-buildpacks
        if: inputs.use-buildpacks
        working-directory: ${{ inputs.maven-module }}
        env:
          DOCKER_PUBLISH_REGISTRY_URL: https://${{ inputs.registry }}
          DOCKER_PUBLISH_REGISTRY_USERNAME: ${{ github.actor }}
          DOCKER_PUBLISH_REGISTRY_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          PER_ARCH_TAG="${{ inputs.registry }}/${{ inputs.image-name }}:ci-${{ github.run_id }}-${{ steps.prep.outputs.platform_pair }}"
          ../mvnw -B -ntp -f ../pom.xml -pl generated-clients -am install -DskipTests=true
          ../mvnw -B -ntp spring-boot:build-image -DskipTests=true \
            -Dspring-boot.build-image.imageName="$PER_ARCH_TAG" \
            -Dspring-boot.build-image.imagePlatform="${{ matrix.platform }}" \
            -Dspring-boot.build-image.publish=true \
            -Ddocker.publishRegistry.url="$DOCKER_PUBLISH_REGISTRY_URL" \
            -Ddocker.publishRegistry.username="$DOCKER_PUBLISH_REGISTRY_USERNAME" \
            -Ddocker.publishRegistry.password="$DOCKER_PUBLISH_REGISTRY_PASSWORD"
          # Capture the platform-specific manifest digest. Newer Paketo lifecycle versions may
          # publish per-arch tags as a single-entry image index; descend to the matching arch when
          # that happens so the merge job pins the platform manifest, not the index wrapper.
          RAW=$(docker buildx imagetools inspect "$PER_ARCH_TAG" --format '{{json .Manifest}}')
          if echo "$RAW" | jq -e '.manifests' >/dev/null 2>&1; then
            ARCH=$(echo "${{ matrix.platform }}" | awk -F/ '{print $2}')
            DIGEST=$(echo "$RAW" | jq -r --arg arch "$ARCH" \
              '.manifests[] | select(.platform.architecture == $arch and .platform.os == "linux") | .digest')
          else
            DIGEST=$(echo "$RAW" | jq -r '.digest')
          fi
          if [[ ! "$DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]]; then
            echo "::error::Refusing to publish: per-arch digest is not a sha256:<64 hex> (got: ${DIGEST:-<empty>})"
            exit 1
          fi
          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"
          echo "Per-arch digest: $DIGEST"

      - name: Export digest
        env:
          DOCKERFILE_DIGEST: ${{ steps.build.outputs.digest }}
          BUILDPACKS_DIGEST: ${{ steps.build-buildpacks.outputs.digest }}
        run: |
          mkdir -p ${{ runner.temp }}/digests
          digest="${BUILDPACKS_DIGEST:-$DOCKERFILE_DIGEST}"
          if [ -z "$digest" ]; then
            echo "::error::No digest produced by either build path"
            exit 1
          fi
          if [ "${{ inputs.single-arch }}" = "true" ]; then
            echo "manifest-digest=$digest" >> "$GITHUB_OUTPUT"
          else
            touch "${{ runner.temp }}/digests/${digest#sha256:}"
          fi

      - name: Apply tags to buildpack image
        if: inputs.single-arch && inputs.use-buildpacks
        env:
          SOURCE_IMAGE: ${{ inputs.registry }}/${{ inputs.image-name }}@${{ steps.build-buildpacks.outputs.digest }}
        run: |
          mapfile -t tags < <(jq -r '.tags[]' <<< "$DOCKER_METADATA_OUTPUT_JSON")
          args=()
          for tag in "${tags[@]}"; do
            args+=(--tag "$tag")
          done
          docker buildx imagetools create "${args[@]}" "$SOURCE_IMAGE"

      - name: Capture single-architecture digest
        id: single-digest
        if: inputs.single-arch
        env:
          IMAGE_TAG_REF: ${{ fromJSON(steps.meta.outputs.json).tags[0] }}
        run: |
          set -euo pipefail
          DIGEST=$(docker buildx imagetools inspect --format '{{.Manifest.Digest}}' "$IMAGE_TAG_REF")
          if [[ ! "$DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]]; then
            echo "::error::Refusing to publish: image digest is invalid (got: ${DIGEST:-<empty>})"
            exit 1
          fi
          echo "manifest-digest=$DIGEST" >> "$GITHUB_OUTPUT"

      - name: Generate build provenance attestation
        if: inputs.single-arch
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-name: ${{ inputs.registry }}/${{ inputs.image-name }}
          subject-digest: ${{ steps.single-digest.outputs.manifest-digest }}
          push-to-registry: true

      - name: Install cosign
        if: inputs.single-arch
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      - name: Sign and verify image
        if: inputs.single-arch
        env:
          IMAGE_REF: ${{ inputs.registry }}/${{ inputs.image-name }}@${{ steps.single-digest.outputs.manifest-digest }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cosign sign --yes "$IMAGE_REF"
          cosign verify "$IMAGE_REF" \
            --certificate-identity-regexp '^https://github\.com/${{ github.repository }}/\.github/workflows/reusable-docker-build\.yml@' \
            --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
            --certificate-github-workflow-repository "${{ github.repository }}" \
            > /dev/null
          gh attestation verify "oci://$IMAGE_REF" --owner "${{ github.repository_owner }}"

      - name: Upload digest
        if: ${{ !inputs.single-arch }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: digests-${{ steps.prep.outputs.image_name }}-${{ steps.prep.outputs.platform_pair }}
          path: ${{ runner.temp }}/digests/*
          if-no-files-found: error
          retention-days: 1

  merge:
    name: Create manifest
    timeout-minutes: 30
    runs-on: ubuntu-latest
    needs: build
    if: ${{ !inputs.single-arch }}
    permissions:
      packages: write
      id-token: write
      attestations: write
    outputs:
      manifest-digest: ${{ steps.digest.outputs.manifest-digest }}
    steps:
      - name: Prepare
        id: prep
        run: |
          image="${{ inputs.image-name }}"
          echo "image_name=${image//\//-}" >> $GITHUB_OUTPUT

      - name: Download digests
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          path: ${{ runner.temp }}/digests
          pattern: digests-${{ steps.prep.outputs.image_name }}-*
          merge-multiple: true

      - name: Log in to Container Registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ inputs.registry }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Prepare tag configuration
        id: tags
        run: |
          {
            echo "tags<<EOF"
            # Default tags. Note: `latest` is NOT applied here — it tracks the latest
            # release and is applied by the release workflow's retag step, together
            # with the X.Y.Z and X.Y tags.
            echo "type=ref,event=branch"
            echo "type=ref,event=pr"
            echo "type=sha,prefix="
            # Custom tags from input
            if [ -n "${{ inputs.tags }}" ]; then
              echo "${{ inputs.tags }}" | while IFS= read -r line || [[ -n "$line" ]]; do
                line=$(echo "$line" | xargs)
                if [ -n "$line" ]; then
                  if [[ "$line" == *"type="* ]]; then
                    echo "$line"
                  else
                    IFS=',' read -ra TAG_ARRAY <<< "$line"
                    for tag in "${TAG_ARRAY[@]}"; do
                      tag=$(echo "$tag" | xargs)
                      if [ -n "$tag" ]; then
                        echo "type=raw,value=${tag}"
                      fi
                    done
                  fi
                fi
              done
            fi
            echo "EOF"
          } >> $GITHUB_OUTPUT

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ inputs.registry }}/${{ inputs.image-name }}
          tags: ${{ steps.tags.outputs.tags }}
          labels: ${{ inputs.labels }}

      - name: Create manifest and push
        working-directory: ${{ runner.temp }}/digests
        run: |
          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
            $(printf '${{ inputs.registry }}/${{ inputs.image-name }}@sha256:%s ' *)

      - name: Inspect image
        run: |
          docker buildx imagetools inspect ${{ inputs.registry }}/${{ inputs.image-name }}:${{ steps.meta.outputs.version }}

      - name: Capture manifest digest
        id: digest
        env:
          IMAGE_TAG_REF: ${{ inputs.registry }}/${{ inputs.image-name }}:${{ steps.meta.outputs.version }}
        run: |
          set -euo pipefail
          DIGEST=$(docker buildx imagetools inspect --format '{{.Manifest.Digest}}' "$IMAGE_TAG_REF")
          if [[ ! "$DIGEST" =~ ^sha256:[a-f0-9]{64}$ ]]; then
            echo "::error::Refusing to publish: manifest digest is not a sha256:<64 lowercase hex> value (got: ${DIGEST:-<empty>})"
            exit 1
          fi
          echo "manifest-digest=$DIGEST" >> "$GITHUB_OUTPUT"
          echo "Multi-arch manifest digest: $DIGEST"

      - name: Generate build provenance attestation
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-name: ${{ inputs.registry }}/${{ inputs.image-name }}
          subject-digest: ${{ steps.digest.outputs.manifest-digest }}
          push-to-registry: true

      - name: Install cosign
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      # --recursive: sign each child manifest so per-platform verify works.
      - name: Sign image with cosign
        env:
          IMAGE_REF: ${{ inputs.registry }}/${{ inputs.image-name }}@${{ steps.digest.outputs.manifest-digest }}
        run: |
          cosign sign --yes --recursive "$IMAGE_REF"

      # Pin cert SAN to this workflow + cross-check the workflow-repo OID.
      - name: Verify signature + attestation
        env:
          IMAGE_REF: ${{ inputs.registry }}/${{ inputs.image-name }}@${{ steps.digest.outputs.manifest-digest }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cosign verify "$IMAGE_REF" \
            --certificate-identity-regexp '^https://github\.com/${{ github.repository }}/\.github/workflows/reusable-docker-build\.yml@' \
            --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
            --certificate-github-workflow-repository "${{ github.repository }}" \
            > /dev/null
          gh attestation verify "oci://$IMAGE_REF" --owner "${{ github.repository_owner }}"