Stirling-PDF/.github/workflows/push-docker.yml

name: Push Docker Image with VersionNumber

on:
  workflow_dispatch:
    inputs:
      build_main_app:
        description: "Build & push the main Stirling-PDF image (latest, fat, ultra-lite)."
        required: false
        type: boolean
        default: true
      build_unoserver:
        description: "Build & push the standalone stirling-unoserver image."
        required: false
        type: boolean
        default: true
      force_unoserver_rebuild:
        description: "Rebuild stirling-unoserver even if its source hash is unchanged."
        required: false
        type: boolean
        default: false
      build_engine:
        description: "Build & push the standalone stirling-engine image."
        required: false
        type: boolean
        default: true
      force_engine_rebuild:
        description: "Rebuild stirling-engine even if its source hash is unchanged."
        required: false
        type: boolean
        default: false
  push:
    branches:
      - release
      - main

# cancel in-progress jobs if a new job is triggered
# This is useful to avoid running multiple builds for the same branch if a new commit is pushed
# or a pull request is updated.
# It helps to save resources and time by ensuring that only the latest commit is built and tested
# This is particularly useful for long-running jobs that may take a while to complete.
# The `group` is set to a combination of the workflow name, event name, and branch name.
# This ensures that jobs are grouped by the workflow and branch, allowing for cancellation of
# in-progress jobs when a new commit is pushed to the same branch or a new pull request is opened.
concurrency:
  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref_name || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  push:
    environment: docker-publish
    if: ${{ vars.CI_PROFILE != 'lite' }}
    runs-on: ubuntu-24.04-8core
    permissions:
      packages: write
      id-token: write
    # On push events these stay 'true'; on workflow_dispatch they follow the inputs.
    env:
      RUN_MAIN_APP: ${{ github.event_name != 'workflow_dispatch' || inputs.build_main_app }}
      RUN_UNOSERVER: ${{ github.event_name != 'workflow_dispatch' || inputs.build_unoserver }}
      RUN_ENGINE: ${{ github.event_name != 'workflow_dispatch' || inputs.build_engine }}
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Cache Gradle
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: gradle-push-docker-v1-${{ runner.os }}-${{ runner.arch }}-jdk-25-${{ hashFiles('gradle/wrapper/gradle-wrapper.properties', 'gradle/libs.versions.toml', 'buildSrc/**', 'settings.gradle', 'build.gradle', 'app/**/build.gradle', 'gradle/**/*.gradle') }}

      - name: Set up JDK 25
        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
        with:
          java-version: "25"
          distribution: "temurin"

      - name: Set up Docker Buildx
        id: buildx
        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0

      - name: Install Task
        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
      - name: Get version number
        id: versionNumber
        run: echo "versionNumber=$(./gradlew printVersion --quiet | tail -1)" >> $GITHUB_OUTPUT
        env:
          MAVEN_USER: ${{ secrets.MAVEN_USER }}
          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
          MAVEN_PUBLIC_URL: ${{ secrets.MAVEN_PUBLIC_URL }}

      - name: Install cosign
        if: github.ref == 'refs/heads/release'
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
        with:
          cosign-release: "v2.4.1"

      - name: Install cosign
        if: github.ref == 'refs/heads/release'
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
        with:
          cosign-release: "v2.4.1"

      - name: Login to Docker Hub
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_API }}

      - name: Login to GitHub Container Registry
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ github.token }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0

      - name: Convert repository owner to lowercase
        id: repoowner
        run: echo "lowercase=$(echo ${{ github.repository_owner }} | awk '{print tolower($0)}')" >> $GITHUB_OUTPUT

      - name: Generate tags for latest
        id: meta
        if: env.RUN_MAIN_APP == 'true'
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/s-pdf
            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf
            ${{ secrets.DOCKER_HUB_ORG_USERNAME }}/stirling-pdf
          tags: |
            type=raw,value=${{ steps.versionNumber.outputs.versionNumber }},enable=${{ github.ref == 'refs/heads/release' }}
            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/release' }}

      - name: Build and push Unified Dockerfile (latest variant)
        id: build-push-latest
        # Empty-tag guard: build-push-action errors when asked to push with no tags.
        if: env.RUN_MAIN_APP == 'true' && steps.meta.outputs.tags != ''
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
          file: ./docker/embedded/Dockerfile
          push: true
          cache-from: type=gha,scope=stirling-pdf-latest
          cache-to: type=gha,mode=max,scope=stirling-pdf-latest
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          # No BASE_VERSION pin: inherit the Dockerfile ARG default (single source of truth).
          build-args: |
            VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true

      - name: Sign regular images
        if: env.RUN_MAIN_APP == 'true' && (github.ref == 'refs/heads/release') && steps.build-push-latest.outputs.digest != ''
        env:
          DIGEST: ${{ steps.build-push-latest.outputs.digest }}
          TAGS: ${{ steps.meta.outputs.tags }}
          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
        run: |
          echo "$TAGS" | tr ',' '\n' | while read -r tag; do
            cosign sign --yes \
              --key env://COSIGN_PRIVATE_KEY \
              "${tag}@${DIGEST}"
          done

      - name: Generate tags for latest-fat
        id: meta-fat
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
        with:
          images: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/s-pdf
            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf
            ${{ secrets.DOCKER_HUB_ORG_USERNAME }}/stirling-pdf
          tags: |
            type=raw,value=${{ steps.versionNumber.outputs.versionNumber }}-fat,enable=${{ github.ref == 'refs/heads/release' }}
            type=raw,value=latest-fat,enable=${{ github.ref == 'refs/heads/release' }}

      - name: Build and push Unified Dockerfile (fat variant)
        id: build-push-fat
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain' && steps.meta-fat.outputs.tags != ''
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
          file: ./docker/embedded/Dockerfile.fat
          push: true
          cache-from: type=gha,scope=stirling-pdf-fat
          cache-to: type=gha,mode=max,scope=stirling-pdf-fat
          tags: ${{ steps.meta-fat.outputs.tags }}
          labels: ${{ steps.meta-fat.outputs.labels }}
          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true

      - name: Sign fat images
        if: env.RUN_MAIN_APP == 'true' && (github.ref == 'refs/heads/release') && steps.build-push-fat.outputs.digest != ''
        env:
          DIGEST: ${{ steps.build-push-fat.outputs.digest }}
          TAGS: ${{ steps.meta-fat.outputs.tags }}
          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
        run: |
          echo "$TAGS" | tr ',' '\n' | while read -r tag; do
            cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
          done

      - name: Generate tags for ultra-lite
        id: meta-lite
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain'
        with:
          images: |
            ${{ secrets.DOCKER_HUB_USERNAME }}/s-pdf
            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/s-pdf
            ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-pdf
            ${{ secrets.DOCKER_HUB_ORG_USERNAME }}/stirling-pdf
          tags: |
            type=raw,value=${{ steps.versionNumber.outputs.versionNumber }}-ultra-lite,enable=${{ github.ref == 'refs/heads/release' }}
            type=raw,value=latest-ultra-lite,enable=${{ github.ref == 'refs/heads/release' }}

      - name: Build and push Unified Dockerfile (ultra-lite variant)
        id: build-push-lite
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain' && steps.meta-lite.outputs.tags != ''
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
          file: ./docker/embedded/Dockerfile.ultra-lite
          push: true
          cache-from: type=gha,scope=stirling-pdf-ultra-lite
          cache-to: type=gha,mode=max,scope=stirling-pdf-ultra-lite
          tags: ${{ steps.meta-lite.outputs.tags }}
          labels: ${{ steps.meta-lite.outputs.labels }}
          build-args: VERSION_TAG=${{ steps.versionNumber.outputs.versionNumber }}
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true

      - name: Sign ultra-lite images
        if: env.RUN_MAIN_APP == 'true' && (github.ref == 'refs/heads/release') && steps.build-push-lite.outputs.digest != ''
        env:
          DIGEST: ${{ steps.build-push-lite.outputs.digest }}
          TAGS: ${{ steps.meta-lite.outputs.tags }}
          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
        run: |
          echo "$TAGS" | tr ',' '\n' | while read -r tag; do
            cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
          done

      # Standalone unoserver image — versioned independently via
      # docker/unoserver/VERSION. release: publish <version>+latest
      # only when the version is new. main/testMain: republish :alpha only
      # when the source hash differs from the published image's annotation.
      - name: Read unoserver image version
        id: unoserverVersion
        if: env.RUN_UNOSERVER == 'true'
        run: |
          version=$(tr -d '[:space:]' < docker/unoserver/VERSION)
          if [ -z "$version" ]; then
            echo "docker/unoserver/VERSION is empty"; exit 1
          fi
          echo "version=${version}" >> "$GITHUB_OUTPUT"
          echo "Unoserver image version (from file): ${version}"

      - name: Compute unoserver image source hash
        id: unoserverHash
        if: env.RUN_UNOSERVER == 'true'
        run: |
          set -eu
          hash=$(cat \
            docker/unoserver/Dockerfile \
            docker/unoserver/entrypoint.sh \
            docker/unoserver/healthcheck.sh \
            docker/unoserver/VERSION \
            | sha256sum | cut -d' ' -f1)
          echo "hash=${hash}" >> "$GITHUB_OUTPUT"
          echo "Unoserver source hash: ${hash}"

      - name: Decide whether to publish unoserver image
        id: unoserverDecision
        if: env.RUN_UNOSERVER == 'true'
        env:
          UNOSERVER_VERSION: ${{ steps.unoserverVersion.outputs.version }}
          UNOSERVER_HASH: ${{ steps.unoserverHash.outputs.hash }}
          UNOSERVER_IMAGE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-unoserver
          UNOSERVER_HASH_ANNOTATION: org.stirlingpdf.unoserver-source-hash
          FORCE_REBUILD: ${{ inputs.force_unoserver_rebuild }}
          GH_REF: ${{ github.ref }}
          EVENT_NAME: ${{ github.event_name }}
        run: |
          set -eu
          mode="skip"
          tags=""

          read_published_hash() {
            local ref="$1"
            docker buildx imagetools inspect "$ref" --raw 2>/dev/null \
              | jq -r --arg key "$UNOSERVER_HASH_ANNOTATION" \
                  '.annotations[$key] // empty' \
              2>/dev/null || true
          }

          # Manual dispatch from any branch routes to the :alpha publish path.
          EFFECTIVE_REF="$GH_REF"
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            EFFECTIVE_REF="refs/heads/testMain"
          fi

          case "$EFFECTIVE_REF" in
            refs/heads/release)
              if [ "${FORCE_REBUILD}" = "true" ]; then
                echo "force_unoserver_rebuild=true — building stable regardless"
                mode="stable"
                tags="${UNOSERVER_IMAGE}:${UNOSERVER_VERSION},${UNOSERVER_IMAGE}:latest"
              elif docker manifest inspect "${UNOSERVER_IMAGE}:${UNOSERVER_VERSION}" >/dev/null 2>&1; then
                echo "stirling-unoserver:${UNOSERVER_VERSION} already on GHCR — skipping"
              else
                echo "stirling-unoserver:${UNOSERVER_VERSION} is new — will publish"
                mode="stable"
                tags="${UNOSERVER_IMAGE}:${UNOSERVER_VERSION},${UNOSERVER_IMAGE}:latest"
              fi
              ;;
            refs/heads/main|refs/heads/testMain)
              published_hash=$(read_published_hash "${UNOSERVER_IMAGE}:alpha")
              if [ "${FORCE_REBUILD}" = "true" ]; then
                echo "force_unoserver_rebuild=true — rebuilding :alpha regardless"
                mode="alpha"
                tags="${UNOSERVER_IMAGE}:alpha"
              elif [ -n "$published_hash" ] && [ "$published_hash" = "$UNOSERVER_HASH" ]; then
                echo "Published :alpha source hash matches (${published_hash}) — skipping"
              else
                if [ -z "$published_hash" ]; then
                  echo ":alpha has no source-hash annotation (first publish or pre-tracking image) — will publish"
                else
                  echo "Source hash changed (was ${published_hash}, now ${UNOSERVER_HASH}) — will publish"
                fi
                mode="alpha"
                tags="${UNOSERVER_IMAGE}:alpha"
              fi
              ;;
            *)
              echo "Branch ${GH_REF} does not publish unoserver image"
              ;;
          esac
          echo "mode=${mode}" >> "$GITHUB_OUTPUT"
          echo "tags=${tags}" >> "$GITHUB_OUTPUT"

      - name: Build and push unoserver image
        id: build-push-unoserver
        if: env.RUN_UNOSERVER == 'true' && steps.unoserverDecision.outputs.mode != 'skip'
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
          file: ./docker/unoserver/Dockerfile
          push: true
          cache-from: type=gha,scope=stirling-unoserver
          cache-to: type=gha,mode=max,scope=stirling-unoserver
          tags: ${{ steps.unoserverDecision.outputs.tags }}
          # Manifest annotation read by the decision step above to detect drift.
          annotations: |
            index:org.stirlingpdf.unoserver-source-hash=${{ steps.unoserverHash.outputs.hash }}
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true

      - name: Sign unoserver image
        if: env.RUN_UNOSERVER == 'true' && steps.unoserverDecision.outputs.mode == 'stable'
        env:
          DIGEST: ${{ steps.build-push-unoserver.outputs.digest }}
          TAGS: ${{ steps.unoserverDecision.outputs.tags }}
          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
        run: |
          if [ -n "$COSIGN_PRIVATE_KEY" ]; then
            echo "$TAGS" | tr ',' '\n' | while read -r tag; do
              cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
            done
          else
            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping unoserver image signing"
          fi

      # Standalone AI engine image, same shape as the unoserver image above.
      - name: Compute engine image source hash
        id: engineHash
        if: env.RUN_ENGINE == 'true'
        run: |
          set -eu
          hash=$( { cat engine/Dockerfile engine/pyproject.toml engine/uv.lock engine/.env; \
                    find engine/src -type f -print0 | sort -z | xargs -0 cat; } \
                  | sha256sum | cut -d' ' -f1)
          echo "hash=${hash}" >> "$GITHUB_OUTPUT"
          echo "Engine source hash: ${hash}"

      - name: Decide whether to publish engine image
        id: engineDecision
        if: env.RUN_ENGINE == 'true'
        env:
          ENGINE_VERSION: ${{ steps.versionNumber.outputs.versionNumber }}
          ENGINE_HASH: ${{ steps.engineHash.outputs.hash }}
          ENGINE_IMAGE: ghcr.io/${{ steps.repoowner.outputs.lowercase }}/stirling-engine
          ENGINE_HASH_ANNOTATION: org.stirlingpdf.engine-source-hash
          FORCE_REBUILD: ${{ inputs.force_engine_rebuild }}
          GH_REF: ${{ github.ref }}
          EVENT_NAME: ${{ github.event_name }}
        run: |
          set -eu
          mode="skip"
          tags=""

          read_published_hash() {
            local ref="$1"
            docker buildx imagetools inspect "$ref" --raw 2>/dev/null \
              | jq -r --arg key "$ENGINE_HASH_ANNOTATION" \
                  '.annotations[$key] // empty' \
              2>/dev/null || true
          }

          # Manual dispatch from any branch routes to the :alpha publish path.
          EFFECTIVE_REF="$GH_REF"
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            EFFECTIVE_REF="refs/heads/testMain"
          fi

          case "$EFFECTIVE_REF" in
            refs/heads/release)
              if [ "${FORCE_REBUILD}" = "true" ]; then
                echo "force_engine_rebuild=true — building stable regardless"
                mode="stable"
                tags="${ENGINE_IMAGE}:${ENGINE_VERSION},${ENGINE_IMAGE}:latest"
              elif docker manifest inspect "${ENGINE_IMAGE}:${ENGINE_VERSION}" >/dev/null 2>&1; then
                echo "stirling-engine:${ENGINE_VERSION} already on GHCR — skipping"
              else
                echo "stirling-engine:${ENGINE_VERSION} is new — will publish"
                mode="stable"
                tags="${ENGINE_IMAGE}:${ENGINE_VERSION},${ENGINE_IMAGE}:latest"
              fi
              ;;
            refs/heads/main|refs/heads/testMain)
              published_hash=$(read_published_hash "${ENGINE_IMAGE}:alpha")
              if [ "${FORCE_REBUILD}" = "true" ]; then
                echo "force_engine_rebuild=true — rebuilding :alpha regardless"
                mode="alpha"
                tags="${ENGINE_IMAGE}:alpha"
              elif [ -n "$published_hash" ] && [ "$published_hash" = "$ENGINE_HASH" ]; then
                echo "Published :alpha source hash matches (${published_hash}) — skipping"
              else
                if [ -z "$published_hash" ]; then
                  echo ":alpha has no source-hash annotation (first publish) — will publish"
                else
                  echo "Source hash changed (was ${published_hash}, now ${ENGINE_HASH}) — will publish"
                fi
                mode="alpha"
                tags="${ENGINE_IMAGE}:alpha"
              fi
              ;;
            *)
              echo "Branch ${GH_REF} does not publish engine image"
              ;;
          esac
          echo "mode=${mode}" >> "$GITHUB_OUTPUT"
          echo "tags=${tags}" >> "$GITHUB_OUTPUT"

      - name: Build and push engine image
        id: build-push-engine
        if: env.RUN_ENGINE == 'true' && steps.engineDecision.outputs.mode != 'skip'
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
          file: ./engine/Dockerfile
          push: true
          cache-from: type=gha,scope=stirling-engine
          cache-to: type=gha,mode=max,scope=stirling-engine
          tags: ${{ steps.engineDecision.outputs.tags }}
          # Manifest annotation read by the decision step above to detect drift.
          annotations: |
            index:org.stirlingpdf.engine-source-hash=${{ steps.engineHash.outputs.hash }}
          platforms: linux/amd64,linux/arm64/v8
          provenance: true
          sbom: true

      - name: Sign engine image
        if: env.RUN_ENGINE == 'true' && steps.engineDecision.outputs.mode == 'stable'
        env:
          DIGEST: ${{ steps.build-push-engine.outputs.digest }}
          TAGS: ${{ steps.engineDecision.outputs.tags }}
          COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
          COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
        run: |
          if [ -n "$COSIGN_PRIVATE_KEY" ]; then
            echo "$TAGS" | tr ',' '\n' | while read -r tag; do
              cosign sign --key env://COSIGN_PRIVATE_KEY --yes "${tag}@${DIGEST}"
            done
          else
            echo "Warning: COSIGN_PRIVATE_KEY not set, skipping engine image signing"
          fi