docker-build.yml

name: Build, Test and Push Docker Image

on:
  workflow_call:
    inputs:
      build-args:
        description:
          "Docker build arguments (multiline format: KEY1=value1\nKEY2=value2)"
        default: ""
        type: string
      image-name:
        description: "Name of Docker Image"
        type: string
        required: true
      image-tag:
        description: "Tag of Docker Image"
        default: "latest"
        type: string
      dockerfile:
        description: "Path to Dockerfile"
        default: "Dockerfile"
        type: string
      context:
        description: "Path to Docker Build Context"
        default: "."
        type: string
      registry:
        description: "Docker Registry"
        default: "docker.io"
        type: string
      push:
        description: "Push Docker Image to Registry"
        default: false
        type: boolean
      attest:
        description: "Generate & sign a keyless SLSA build provenance attestation for the pushed image (the CALLER must grant id-token: write and attestations: write)"
        default: false
        type: boolean
      dockerhub-login:
        description: "Log in to Docker Hub before the build, to avoid anonymous pull rate limits on base images. Ignored when `push: true` and `registry` already points at Docker Hub, since the push login covers that host"
        default: true
        type: boolean
      security-scan:
        description: "Enable Trivy Security Scan"
        default: true
        type: boolean
      security-report:
        description: 'Security Report Mode (`"sarif"` | `"comment"`; ignored if `security-scan: false`)'
        default: "sarif"
        type: string
      trivy-version:
        description: "Trivy security scanner version"
        default: "v0.71.0"
        type: string
      hadolint:
        description: "Enable Hadolint"
        default: true
        type: boolean
      platform:
        description: "Build platform"
        default: "linux/amd64"
        type: string
      runner:
        description: "GitHub Actions runner label"
        default: "ubuntu-latest"
        type: string
      artifact-name:
        description: "Name of an artifact to download into the build context before building, e.g. a jar produced by an earlier job (leave empty to skip)"
        default: ""
        type: string
      artifact-path:
        description: "Destination path for the downloaded artifact, relative to the workspace (ignored if `artifact-name` is empty)"
        default: ""
        type: string
    secrets:
      dockerhub-username:
        required: false
      dockerhub-password:
        required: false
      username:
        required: false
      password:
        required: false
    outputs:
      checksum:
        description: "Checksum of the Docker image"
        value: ${{ jobs.build.outputs.checksum }}
jobs:
  build:
    runs-on: ${{ inputs.runner }}
    outputs:
      checksum: ${{ steps.checksum.outputs.checksum }}

    # avoid shell injection through string interpolation
    env:
      IMAGE_TAG: ${{ inputs.image-tag }}
      OCI_IMAGE: ${{ inputs.image-name }}:${{ inputs.image-tag }}
      PLATFORM: ${{ inputs.platform }}
      PUSH: ${{ inputs.push }}
      REGISTRY: ${{ inputs.registry }}
      REPORT_MODE: ${{ inputs.security-report }}

    steps:
      - name: Validate platform input
        run: |
          if [ "$PLATFORM" != "linux/amd64" ] && [ "$PLATFORM" != "linux/arm64" ] ; then
            echo "❌ Error: Invalid platform: $PLATFORM"
            echo "Valid platforms are 'linux/amd64' or 'linux/arm64'"
            exit 1
          fi

          echo "✅ Platform validation passed: $PLATFORM"

      - name: Validate security report mode input
        if: ${{ inputs.security-scan }}
        run: |
          if [ "$REPORT_MODE" != "comment" ] && [ "$REPORT_MODE" != "sarif" ] ; then
            echo "❌ Error: Invalid security report mode: $REPORT_MODE"
            echo "Valid modes are 'comment' or 'sarif'"
            exit 1
          fi

          echo "✅ Security report mode validation passed: $REPORT_MODE"

      # Resolves whether the Docker Hub pull login is still needed, and fails fast
      # when the push credentials required by `push: true` are missing.
      - name: Validate registry credentials
        id: validate-credentials
        env:
          DOCKERHUB_LOGIN: ${{ inputs.dockerhub-login }}
          DOCKERHUB_USERNAME: ${{ secrets.dockerhub-username }}
          DOCKERHUB_PASSWORD: ${{ secrets.dockerhub-password }}
          REGISTRY_USERNAME: ${{ secrets.username }}
          REGISTRY_PASSWORD: ${{ secrets.password }}
        run: |
          set -euo pipefail

          if [ "$PUSH" = "true" ] && { [ -z "$REGISTRY_USERNAME" ] || [ -z "$REGISTRY_PASSWORD" ]; }; then
            echo "❌ Error: push is enabled but 'username'/'password' are missing"
            echo "Pass the secrets of the target registry ($REGISTRY), or set push: false"
            exit 1
          fi

          NEEDS_DOCKERHUB_LOGIN=false
          if [ "$DOCKERHUB_LOGIN" != "true" ]; then
            echo "✅ Docker Hub login disabled by input"
          elif [ "$PUSH" = "true" ] && { [ "$REGISTRY" = "docker.io" ] || [ "$REGISTRY" = "index.docker.io" ] || [ "$REGISTRY" = "registry-1.docker.io" ]; }; then
            # The Docker Registry login below would authenticate the same host as
            # Docker Hub login and would just overwrite credentials in ~/.docker/config.json.
            # So pushing to Docker Hub does not require the Docker Hub secrets at all.
            echo "✅ Skipping the Docker Hub login: pushing to $REGISTRY already authenticates that host"
          elif [ -z "$DOCKERHUB_USERNAME" ] || [ -z "$DOCKERHUB_PASSWORD" ]; then
            echo "❌ Error: dockerhub-login is enabled but 'dockerhub-username'/'dockerhub-password' are missing"
            echo "Pass the Docker Hub secrets, or set dockerhub-login: false"
            exit 1
          else
            NEEDS_DOCKERHUB_LOGIN=true
          fi

          echo "needs-dockerhub-login=$NEEDS_DOCKERHUB_LOGIN" >> "$GITHUB_OUTPUT"

      - name: Checkout Repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Download build artifact
        if: ${{ inputs.artifact-name != '' }}
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: ${{ inputs.artifact-name }}
          path: ${{ inputs.artifact-path }}

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

      # Only needed to raise the pull rate limit on Docker Hub hosted base images
      # when push `registry` is not Docker Hub.
      - name: Login to Docker Hub
        if: ${{ steps.validate-credentials.outputs.needs-dockerhub-login == 'true' }}
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.dockerhub-username }}
          password: ${{ secrets.dockerhub-password }}

      - name: Login to Docker Registry
        if: ${{ inputs.push }}
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ inputs.registry }}
          username: ${{ secrets.username }}
          password: ${{ secrets.password }}

      - name: Build Docker image
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          build-args: ${{ inputs.build-args }}
          context: ${{ inputs.context }}
          file: ${{ inputs.dockerfile }}
          platforms: ${{ inputs.platform }}
          load: true # Make the image available on runner
          push: false # Don't push yet, wait for security checks
          tags: ${{ inputs.image-name }}:${{ inputs.image-tag }}

      - name: Run Trivy vulnerability scanner
        id: trivy
        if: ${{ inputs.security-scan }}
        # https://github.com/aquasecurity/trivy-action/issues/541
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ inputs.image-name }}:${{ inputs.image-tag }}
          format: ${{ (inputs.security-report == 'sarif' && 'sarif') || 'table' }}
          vuln-type: "os,library"
          hide-progress: true
          output: ${{ (inputs.security-report == 'sarif' && 'trivy-results.sarif') || 'trivy.txt' }}
          # following https://github.com/aquasecurity/trivy/discussions/10265
          version: ${{ inputs.trivy-version }}

      - name: Read Trivy report file
        id: read_trivy
        if: github.event_name == 'pull_request' && inputs.security-scan && inputs.security-report == 'comment'
        run: |
          {
            echo "report<<EOF"
            cat trivy.txt
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Find existing Trivy comment
        if: github.event_name == 'pull_request' && inputs.security-scan && inputs.security-report == 'comment'
        id: find_trivy
        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: "github-actions[bot]"
          body-includes: "Trivy Security ${{ inputs.platform }} Scan Results"

      - name: Create or update Trivy comment
        if: github.event_name == 'pull_request' && inputs.security-scan && inputs.security-report == 'comment'
        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.pull_request.number }}
          comment-id: ${{ steps.find_trivy.outputs.comment-id }}
          edit-mode: replace
          body: |
            <!-- trivy-scan -->
            ### 🔒 Trivy Security ${{ inputs.platform }} Scan Results
            <details><summary>Click to expand detailed results</summary>

            ```bash
            ${{ steps.read_trivy.outputs.report }}
            ```
            </details>

      - name: Upload Trivy scan results to GitHub Security tab
        if: github.event_name == 'pull_request' && inputs.security-scan && inputs.security-report == 'sarif'
        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
        with:
          sarif_file: "trivy-results.sarif"

      - name: Run Hadolint Dockerfile linter
        id: hadolint
        if: ${{ inputs.hadolint }}
        uses: hadolint/hadolint-action@06be81baf89a55ffd0e24b8f04a4185738dd3387 # v3.5.0
        with:
          dockerfile: ${{ inputs.dockerfile }}
          output-file: hadolint.txt
          no-fail: true

      - name: Read Hadolint report file
        id: read_hadolint
        if: ${{ inputs.hadolint }}
        run: |
          {
            echo "report<<EOF"
            cat hadolint.txt
            echo "EOF"
          } >> "$GITHUB_OUTPUT"
          cat hadolint.txt

      - name: Find existing Hadolint comment
        id: find_hadolint
        if: ${{ github.event_name == 'pull_request' && inputs.hadolint }}
        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: "github-actions[bot]"
          body-includes: "Hadolint Dockerfile Lint Results"

      - name: Create or update Hadolint comment
        if: ${{ github.event_name == 'pull_request' && inputs.hadolint && steps.read_hadolint.outputs.report != '' }}
        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.pull_request.number }}
          comment-id: ${{ steps.find_hadolint.outputs.comment-id }}
          edit-mode: replace
          body: |
            <!-- hadolint-scan -->
            ### 🐳 Hadolint Dockerfile Lint Results
            <details><summary>Click to expand detailed results</summary>

            ```bash
            ${{ steps.read_hadolint.outputs.report }}
            ```
            </details>

      - name: Fail build on CRITICAL or HIGH vulnerabilities
        if: ${{ inputs.security-scan }}
        # https://github.com/aquasecurity/trivy-action/issues/541
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: ${{ inputs.image-name }}:${{ inputs.image-tag }}
          format: table
          ignore-unfixed: true
          vuln-type: "os,library"
          severity: "CRITICAL,HIGH"
          hide-progress: true
          skip-setup-trivy: true
          exit-code: 1

      - name: Push Docker image
        if: ${{ inputs.push }}
        run: docker push "$OCI_IMAGE"

      - name: Record the pushed image tag
        if: ${{ inputs.push }}
        run: |
          echo "$IMAGE_TAG" > image-tag.txt

      # The promote workflow runs from a separate tag push and reads this artifact
      # from the CI run, instead of reconstructing the tag from a prefix.
      - name: Upload the image tag for the promote workflow
        if: ${{ inputs.push }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: docker-image-tag
          path: image-tag.txt

      - name: Compute checksum of the Docker image
        id: checksum
        run: |
          # Extract SHA256 digest and expose it in both 0x... and sha256:... formats
          INSPECT=$(docker image inspect "$OCI_IMAGE")
          DIGEST=$(echo "$INSPECT" | jq -r 'if .[0].RepoDigests[0] then .[0].RepoDigests[0] | split("@sha256:")[1] else .[0].Id | split(":")[1] end')
          echo "checksum=0x${DIGEST}" >> "$GITHUB_OUTPUT"
          echo "digest=sha256:${DIGEST}" >> "$GITHUB_OUTPUT"

      - name: Summarise the build
        env:
          PUSH: ${{ inputs.push }}
          REGISTRY: ${{ inputs.registry }}
          DIGEST: ${{ steps.checksum.outputs.digest }}
          CHECKSUM: ${{ steps.checksum.outputs.checksum }}
        run: |
          {
            echo "### 🐳 Built \`$OCI_IMAGE\`"
            echo ""
            echo "<table><tbody>"
            echo "<tr><td><b>Platform</b></td><td>$PLATFORM</td></tr>"
            echo "<tr><td><b>Registry</b></td><td>$REGISTRY</td></tr>"
            echo "<tr><td><b>Digest</b></td><td><code>$DIGEST</code></td></tr>"
            echo "<tr><td><b>Checksum</b></td><td><code>$CHECKSUM</code></td></tr>"
            if [ "$PUSH" = "true" ]; then
              echo "<tr><td><b>Pushed</b></td><td>✅</td></tr>"
            fi
            echo "</tbody></table>"
          } >> "$GITHUB_STEP_SUMMARY"

      # --- SLSA provenance attestation -----
      # Requires the permissions id-token: write + attestations: write.
      - name: Generate & sign SLSA provenance (keyless)
        if: ${{ inputs.attest && inputs.push }}
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-name: ${{ inputs.image-name }}
          subject-digest: ${{ steps.checksum.outputs.digest }}
          push-to-registry: false # Do not push attestation to registry

      - name: Cleanup files
        if: always()
        run: |
          rm -f trivy.txt trivy-results.sarif image-tag.txt
          docker image rm -f "$OCI_IMAGE"