zfnd-build-docker-image.yml

# This workflow automates the building and pushing of Docker images based on user-defined inputs. It includes:
# - Accepting various inputs like image name, Dockerfile path, target, and additional Rust-related parameters.
# - Authenticates with Google Cloud and logs into Google Artifact Registry and DockerHub.
# - Uses Docker Buildx for improved build performance and caching.
# - Builds the Docker image and pushes it to both Google Artifact Registry and potentially DockerHub, depending on release type.
# - Manages caching strategies to optimize build times across different branches.
# - Uses Docker Scout to display vulnerabilities and recommendations for the latest built image.
name: Build docker image

on:
  workflow_call:
    inputs:
      source_sha:
        description: The immutable commit to build
        required: true
        type: string
      image_name:
        required: true
        type: string
      dockerfile_path:
        required: true
        type: string
      dockerfile_target:
        required: true
        type: string
      short_sha:
        description: "Git short SHA to embed in the build. Defaults to the short source_sha. Pass empty string to disable."
        required: false
        type: string
        default: auto
      rust_backtrace:
        required: false
        type: string
      rust_lib_backtrace:
        required: false
        type: string
      # defaults to: vars.RUST_LOG
      rust_log:
        required: false
        type: string
      features:
        required: false
        type: string
      no_cache:
        description: Disable the Docker cache for this build
        required: false
        type: boolean
        default: false
      publish_to_dockerhub:
        description: "Whether to publish to Docker Hub. Set to true only in release-binaries.yml to create official production images. Defaults to false to prevent duplicate publishing from deploy-nodes.yml."
        required: false
        type: boolean
        default: false
      environment:
        description: "Environment to use for the build (commonly dev)"
        required: false
        type: string
        default: ''

    secrets:
      DOCKERHUB_USERNAME:
        required: false
      DOCKERHUB_TOKEN:
        required: false

    outputs:
      image:
        description: The immutable Google Artifact Registry image reference
        value: ${{ jobs.merge.outputs.image }}
      image_digest:
        description: The image digest to be used on a caller workflow
        value: ${{ jobs.merge.outputs.image_digest }}

permissions:
  contents: read

env:
  FEATURES: ${{ inputs.features }}
  RUST_LOG: ${{ inputs.rust_log || vars.RUST_LOG }}
  CARGO_INCREMENTAL: ${{ vars.CARGO_INCREMENTAL }}

jobs:
  # Resolve the workflow environment once so build/merge jobs and downstream
  # consumers route to the same dev/stage/prod GitHub environment.
  determine-environment:
    name: Determine environment
    runs-on: ubuntu-latest
    timeout-minutes: 1
    outputs:
      environment: ${{ steps.set.outputs.environment }}
    steps:
      - id: set
        env:
          INPUT_ENVIRONMENT: ${{ inputs.environment }}
          EVENT_NAME: ${{ github.event_name }}
        run: |
          if [ -n "$INPUT_ENVIRONMENT" ]; then
            ENV="$INPUT_ENVIRONMENT"
          else
            case "$EVENT_NAME" in
              release)      ENV="prod" ;;
              pull_request) ENV="dev" ;;
              *)            ENV="stage" ;;
            esac
          fi
          echo "environment=$ENV" >> "$GITHUB_OUTPUT"

  prepare-matrix:
    name: Prepare build matrix
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - name: Set build matrix
        id: set-matrix
        env:
          AMD64_RUNNER: ${{ vars.DOCKER_BUILD_RUNNER_AMD64 || 'ubuntu-latest' }}
          ARM64_RUNNER: ${{ vars.DOCKER_BUILD_RUNNER_ARM64 || 'ubuntu-24.04-arm' }}
          DOCKERFILE_TARGET: ${{ inputs.dockerfile_target }}
        run: |
          # Runners are configurable via repository variables to allow larger runners
          # for ZcashFoundation (more disk space) while forks use default runners.
          # Runtime builds: AMD64 + ARM64 (multi-arch)
          # Other targets: AMD64 only (lightwalletd dependency)
          if [[ "$DOCKERFILE_TARGET" == "runtime" ]]; then
            MATRIX='{"include":[{"platform":"linux/amd64","runner":"'"$AMD64_RUNNER"'"},{"platform":"linux/arm64","runner":"'"$ARM64_RUNNER"'"}]}'
          else
            MATRIX='{"include":[{"platform":"linux/amd64","runner":"'"$AMD64_RUNNER"'"}]}'
          fi
          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
          echo "Runners: AMD64=$AMD64_RUNNER, ARM64=$ARM64_RUNNER"
          echo "Platforms: $(echo "$MATRIX" | jq -r '.include[].platform' | paste -sd ',' -)"

  build:
    name: Build images (${{ matrix.platform }})
    needs: [determine-environment, prepare-matrix]
    timeout-minutes: 210
    runs-on: ${{ matrix.runner }}
    environment: ${{ needs.determine-environment.outputs.environment }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.prepare-matrix.outputs.matrix) }}
    outputs:
      image_digest: ${{ steps.docker_build.outputs.digest || steps.docker_build_no_attestations.outputs.digest }}
      image_name: ${{ fromJSON(steps.docker_build.outputs.metadata || steps.docker_build_no_attestations.outputs.metadata || '{}')['image.name'] }}
    permissions:
      contents: read
      id-token: write
      pull-requests: write # for `docker-scout` to be able to write the comment
    env:
      DOCKER_BUILD_SUMMARY: ${{ vars.DOCKER_BUILD_SUMMARY }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
        with:
          persist-credentials: false
          ref: ${{ inputs.source_sha }}

      - name: Set source metadata
        env:
          SOURCE_SHA: ${{ inputs.source_sha }}
        run: |
          echo "SOURCE_SHA_SHORT=${SOURCE_SHA:0:7}" >> "$GITHUB_ENV"
          echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)" >> "$GITHUB_ENV"

      # Automatic tag management and OCI Image Format Specification for labels
      - name: Docker meta
        id: meta
        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf #v6.0.0
        with:
          # list of Docker images to use as base name for tags
          # Docker Hub publishing requires ALL conditions to be true:
          # - inputs.publish_to_dockerhub must be explicitly set to true (defaults to false)
          # - Event must be a release (not a pre-release)
          # This prevents duplicate publishing when both release-binaries.yml and deploy-nodes.yml run
          # Ref: https://github.com/orgs/community/discussions/26281#discussioncomment-3251177
          images: |
            us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }}
            zfnd/${{ inputs.image_name }},enable=${{ inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease }}
          labels: |
            org.opencontainers.image.revision=${{ inputs.source_sha }}
          # generate Docker tags based on the following events/attributes
          tags: |
            # These DockerHub release tags support the following use cases:
            # - `latest`: Automatically points to the most recent Zebra release, ensuring users always get the latest stable version when pulling or updating.
            # - `1.x.y`: Represents a specific semantic version (e.g., 1.2.3), allowing users to pin to an exact version for stability, preventing automatic upgrades.
            #
            type=semver,pattern={{version}}
            # CI-only tags (not published to DockerHub, only in Google Artifact Registry):
            # - `pr-xxx`: Tags images with the pull request number for CI tracking during PR workflows.
            # - `branch-name`: Tags images with the branch name (e.g., `main`, `dev`) for CI builds on branch pushes.
            # - `edge`: Tags the latest build on the default branch (e.g., `main`), used in CI to represent the cutting-edge version for testing.
            # - `schedule`: Tags images built during scheduled workflows (e.g., nightly or periodic builds) for CI monitoring and testing.
            type=ref,event=pr
            type=ref,event=branch
            type=edge,enable={{is_default_branch}}
            type=schedule
            # - `sha-xxxxxx`: Uses the commit SHA (shortened) to tag images for precise identification.
            # Applied during pull requests and branch pushes to ensure CI tests use the exact image from the last commit.
            type=sha,event=pr
            type=sha,event=branch

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 #v3.0.0
        with:
          workload_identity_provider: "${{ vars.GCP_WIF }}"
          service_account: "${{ vars.GCP_ARTIFACTS_SA }}"
          token_format: access_token
          # Some builds might take over an hour, and Google's default lifetime duration for
          # an access token is 1 hour (3600s). We increase this to 3 hours (10800s)
          # as some builds take over an hour.
          access_token_lifetime: 10800s

      - name: Login to Google Artifact Registry
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 #v4.1.0
        with:
          registry: us-docker.pkg.dev
          username: oauth2accesstoken
          password: ${{ steps.auth.outputs.access_token }}

      - name: Login to DockerHub
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 #v4.1.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # Setup Docker Buildx to use Docker Build Cloud
      - name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd #v4.0.0 # zizmor: ignore[cache-poisoning] -- shared Docker Build Cloud cache across envs, isolation fix pending
        with:
          version: lab:latest
          driver: ${{ vars.DOCKER_BUILDER || 'docker' }}
          endpoint: zfnd/zebra

      # Build and push image by digest to Google Artifact Registry
      # Images are pushed by digest only and will be merged into multi-arch manifest in the merge job
      # With provenance and SBOM (ZcashFoundation repository only)
      - name: Build & push (with attestations)
        id: docker_build
        if: github.repository_owner == 'ZcashFoundation'
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f #v7.1.0
        with:
          platforms: ${{ matrix.platform }}
          target: ${{ inputs.dockerfile_target }}
          context: .
          file: ${{ inputs.dockerfile_path }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            SHORT_SHA=${{ inputs.short_sha == 'auto' && env.SOURCE_SHA_SHORT || inputs.short_sha }}
            RUST_LOG=${{ env.RUST_LOG }}
            CARGO_INCREMENTAL=${{ env.CARGO_INCREMENTAL }}
            FEATURES=${{ env.FEATURES }}
            SOURCE_DATE_EPOCH=${{ env.SOURCE_DATE_EPOCH }}
          outputs: type=image,name=us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }},push-by-digest=true,name-canonical=true,push=true,rewrite-timestamp=true
          # It's recommended to build images with max-level provenance attestations
          # https://docs.docker.com/build/ci/github-actions/attestations/
          provenance: mode=max
          sbom: true
          # Don't read from the cache if the caller disabled it.
          # https://docs.docker.com/engine/reference/commandline/buildx_build/#options
          no-cache: ${{ inputs.no_cache }}

      # Build and push image by digest without attestations (contributor forks)
      # Images are pushed by digest only and will be merged into multi-arch manifest in the merge job
      - name: Build & push (without attestations)
        id: docker_build_no_attestations
        if: github.repository_owner != 'ZcashFoundation'
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f #v7.1.0
        with:
          platforms: ${{ matrix.platform }}
          target: ${{ inputs.dockerfile_target }}
          context: .
          file: ${{ inputs.dockerfile_path }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            SHORT_SHA=${{ inputs.short_sha == 'auto' && env.SOURCE_SHA_SHORT || inputs.short_sha }}
            RUST_LOG=${{ env.RUST_LOG }}
            CARGO_INCREMENTAL=${{ env.CARGO_INCREMENTAL }}
            FEATURES=${{ env.FEATURES }}
            SOURCE_DATE_EPOCH=${{ env.SOURCE_DATE_EPOCH }}
          outputs: type=image,name=us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }},push-by-digest=true,name-canonical=true,push=true,rewrite-timestamp=true
          # Don't read from the cache if the caller disabled it.
          # https://docs.docker.com/engine/reference/commandline/buildx_build/#options
          no-cache: ${{ inputs.no_cache }}

      # Export digest for multi-arch manifest merge
      - name: Export digest
        env:
          IMAGE_DIGEST: ${{ steps.docker_build.outputs.digest || steps.docker_build_no_attestations.outputs.digest }}
        run: |
          mkdir -p /tmp/digests
          touch "/tmp/digests/${IMAGE_DIGEST#sha256:}"

      # Upload digest as artifact for merge job
      - name: Upload digest
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a #v7.0.1
        with:
          name: digests-${{ inputs.image_name }}-${{ matrix.platform == 'linux/amd64' && 'amd64' || 'arm64' }}
          path: /tmp/digests/*
          if-no-files-found: error
          retention-days: 1

  # Merge multi-platform manifests and apply tags
  # This job creates a multi-arch manifest from all platform-specific images built in parallel
  # and applies all necessary tags to both GCP Artifact Registry and DockerHub
  merge:
    name: Create multi-arch manifest
    runs-on: ubuntu-latest
    needs: [determine-environment, prepare-matrix, build]
    environment: ${{ needs.determine-environment.outputs.environment }}
    permissions:
      contents: read
      id-token: write
      pull-requests: write
      attestations: write
    outputs:
      image: ${{ steps.create.outputs.image }}
      image_digest: ${{ steps.create.outputs.digest }}
    steps:
      # Download all platform digests
      - name: Download digests
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c #v8.0.1
        with:
          path: /tmp/digests
          pattern: digests-${{ inputs.image_name }}-*
          merge-multiple: true

      # Docker meta for tag generation
      - name: Docker meta
        id: meta
        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf #v6.0.0
        with:
          images: |
            us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }}
            zfnd/${{ inputs.image_name }},enable=${{ inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease }}
          tags: |
            type=semver,pattern={{version}}
            type=ref,event=pr
            type=ref,event=branch
            type=edge,enable={{is_default_branch}}
            type=schedule
            type=sha,event=pr
            type=sha,event=branch

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 #v3.0.0
        with:
          workload_identity_provider: "${{ vars.GCP_WIF }}"
          service_account: "${{ vars.GCP_ARTIFACTS_SA }}"
          token_format: access_token
          access_token_lifetime: 3600s

      - name: Login to Google Artifact Registry
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 #v4.1.0
        with:
          registry: us-docker.pkg.dev
          username: oauth2accesstoken
          password: ${{ steps.auth.outputs.access_token }}

      # Login to DockerHub when:
      # 1. Publishing images for a release (not prerelease), OR
      # 2. Running Docker Scout on release PRs (requires DockerHub authentication)
      - name: Login to DockerHub
        if: (inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease) || (inputs.dockerfile_target == 'runtime' && contains(github.event.pull_request.title, 'Release v'))
        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 #v4.1.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # Create multi-arch manifest and push to registries
      - name: Create manifest and push
        id: create
        working-directory: /tmp/digests
        run: |
          image_sources=()
          for digest in *; do
            image_sources+=("${IMAGE_REPOSITORY}@sha256:${digest}")
          done

          # The -t flags expand to separate args.
          # shellcheck disable=SC2046
          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
            --metadata-file /tmp/manifest-metadata.json \
            "${image_sources[@]}"

          digest=$(jq -er '."containerimage.descriptor".digest' /tmp/manifest-metadata.json)
          echo "digest=${digest}" >> "$GITHUB_OUTPUT"
          echo "image=${IMAGE_REPOSITORY}@${digest}" >> "$GITHUB_OUTPUT"
        env:
          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta.outputs.json }}
          IMAGE_REPOSITORY: us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }}

      # Sign + attest the released image
      - name: Attest build provenance
        if: inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-name: docker.io/zfnd/${{ inputs.image_name }}
          subject-digest: ${{ steps.create.outputs.digest }}
          push-to-registry: true

      - name: Install Cosign
        if: inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      - name: Sign images with Cosign
        if: inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease
        env:
          DIGEST: ${{ steps.create.outputs.digest }}
          GAR_IMAGE: us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }}
          HUB_IMAGE: docker.io/zfnd/${{ inputs.image_name }}
        run: |
          cosign sign --yes "${GAR_IMAGE}@${DIGEST}"
          cosign sign --yes "${HUB_IMAGE}@${DIGEST}"

      - name: Generate SBOM
        if: inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease
        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
        with:
          image: docker.io/zfnd/${{ inputs.image_name }}@${{ steps.create.outputs.digest }}
          format: spdx-json
          output-file: sbom.spdx.json
          upload-artifact: false

      - name: Attest SBOM
        if: inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease
        uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0
        with:
          subject-name: docker.io/zfnd/${{ inputs.image_name }}
          subject-digest: ${{ steps.create.outputs.digest }}
          sbom-path: sbom.spdx.json
          push-to-registry: true

      # Fail the release if the signature or attestations don't verify.
      - name: Verify release signatures
        if: inputs.publish_to_dockerhub && github.event_name == 'release' && !github.event.release.prerelease
        env:
          DIGEST: ${{ steps.create.outputs.digest }}
          HUB_IMAGE: docker.io/zfnd/${{ inputs.image_name }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cosign verify "${HUB_IMAGE}@${DIGEST}" \
            --certificate-identity-regexp='^https://github\.com/ZcashFoundation/zebra/\.github/workflows/zfnd-build-docker-image\.yml@' \
            --certificate-oidc-issuer='https://token.actions.githubusercontent.com'
          gh attestation verify "oci://${HUB_IMAGE}@${DIGEST}" \
            --owner ZcashFoundation \
            --signer-workflow ZcashFoundation/zebra/.github/workflows/zfnd-build-docker-image.yml

      # For the merged multi-arch manifest, display:
      # - the vulnerabilities (ignoring the base image, and only displaying vulnerabilities with a critical or high security severity)
      # - the available recommendations
      # - compare it to the latest image indexed in Docker Hub (only displaying changed packages and vulnerabilities that already have a fix)
      #
      # Record the image to Scout environment based on the event type, for example:
      # - `prod` for a release event
      # - `stage` for a push event to the main branch
      # - `dev` for a pull request event
      - name: Docker Scout
        id: docker-scout
        uses: docker/scout-action@cd72f264beff1cd72735de31148b9d3244a0234a #v1.21.0
        # We only run Docker Scout on the `runtime` target, as the other targets are not meant to be released
        # and are commonly used for testing, and thus are ephemeral.
        # TODO: Remove the `contains` check once we have a better way to determine if just new vulnerabilities are present.
        # See: https://github.com/docker/scout-action/issues/56
        if: ${{ inputs.dockerfile_target == 'runtime' && contains(github.event.pull_request.title, 'Release v') }}
        with:
          command: cves,recommendations,compare,environment
          image: us-docker.pkg.dev/${{ vars.GCP_PROJECT }}/zebra/${{ inputs.image_name }}:${{ steps.meta.outputs.version }}
          to: zfnd/zebra:latest
          ignore-base: true
          ignore-unchanged: true
          only-fixed: true
          only-severities: critical,high
          environment: ${{ (github.event_name == 'release' && !github.event.release.prerelease && 'prod') || (github.event_name == 'push' && github.ref_name == 'main' && 'stage') || (github.event_name == 'pull_request' && 'dev') }}
          organization: zfnd
          github-token: ${{ secrets.GITHUB_TOKEN }} # to be able to write the comment