docker-release.yml

---
# Pullbox Docker Release Pipeline
# Builds AMD64 and ARM64 images concurrently, validates the AMD64 candidate,
# publishes multi-platform manifests to GHCR and Docker Hub, signs both
# registries with Cosign, and verifies the published release.
#
# Security: All actions pinned to full SHA. Release tags or explicit manual
# develop dispatches are the only publishing triggers. Development tags are
# promoted only after exact-commit validation and both registry signatures pass.

name: Docker Release

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:

permissions:
  contents: read

env:
  GHCR_IMAGE: ghcr.io/${{ github.repository }}
  DOCKERHUB_IMAGE: docker.io/pullbox/pullbox
  PYTHON_DEFAULT: "3.14"

concurrency:
  group: docker-release-${{ github.ref || github.run_id }}
  cancel-in-progress: false

jobs:
  # Resolve release metadata once without occupying a Docker runner.
  build:
    name: Prepare Docker Release
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      actions: read
      checks: read
    outputs:
      image-tags: ${{ steps.meta.outputs.tags }}
      candidate-tags: ${{ steps.release-metadata.outputs.candidate_tags }}
      development-tag: ${{ steps.release-metadata.outputs.development_tag }}
      image-labels: ${{ steps.meta.outputs.labels }}
      image-annotations: ${{ steps.meta.outputs.annotations }}
      image-version: ${{ steps.version.outputs.version }}
      build-date: ${{ steps.release-metadata.outputs.build_date }}
      build-sha: ${{ steps.resolve-sha.outputs.sha }}
      release-tag: ${{ steps.resolve-tag.outputs.tag }}
      is-release: ${{ steps.resolve-tag.outputs.is_release }}
      is-prerelease: ${{ steps.resolve-tag.outputs.is_prerelease }}
    steps:
      - name: Validate publishing trigger
        run: |
          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ] && [ "${GITHUB_REF}" = "refs/heads/develop" ]; then
            exit 0
          fi
          if [ "${GITHUB_EVENT_NAME}" = "push" ] && [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
            exit 0
          fi
          echo "::error::Manual image publication is restricted to develop; releases require a version-tag push."
          exit 1

      - name: Resolve correct SHA
        id: resolve-sha
        run: |
          echo "sha=${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
          if [ "${GITHUB_REF_TYPE}" = "tag" ] && [[ "${GITHUB_REF_NAME}" == v* ]]; then
            echo "release_tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
          else
            echo "release_tag=" >> "$GITHUB_OUTPUT"
          fi

      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ steps.resolve-sha.outputs.sha }}
          fetch-depth: 0
          fetch-tags: true

      - name: Require validated development commit
        if: github.event_name == 'workflow_dispatch'
        env:
          GH_TOKEN: ${{ github.token }}
        run: python3 .github/scripts/validate-development-image.py

      - name: Resolve tag from trigger
        id: resolve-tag
        run: |
          TAG="${{ steps.resolve-sha.outputs.release_tag }}"
          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
          if [ -n "${TAG}" ]; then
            echo "is_release=true" >> "$GITHUB_OUTPUT"
            if [[ "${TAG}" == *-* ]]; then
              echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
            else
              echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
            fi
          else
            echo "is_release=false" >> "$GITHUB_OUTPUT"
            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Extract version
        id: version
        run: |
          VERSION=$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/pullbox/__init__.py | head -1)
          if [ -z "${VERSION}" ]; then
            echo "::error::Unable to extract Pullbox version from src/pullbox/__init__.py"
            exit 1
          fi
          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ] && [[ "${VERSION}" != *-dev ]]; then
            echo "::error::Development images require a -dev application version."
            exit 1
          fi
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"

      - name: Capture release metadata
        id: release-metadata
        run: |
          echo "build_date=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> "$GITHUB_OUTPUT"
          echo "development_tag=sha-${GITHUB_SHA}-run-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"
          {
            echo "candidate_tags<<EOF"
            echo "${GHCR_IMAGE}:candidate-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
            echo "${DOCKERHUB_IMAGE}:candidate-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Docker metadata
        id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        env:
          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
        with:
          images: |
            ${{ env.GHCR_IMAGE }}
            ${{ env.DOCKERHUB_IMAGE }}
          tags: |
            type=semver,pattern={{version}},value=${{ steps.resolve-tag.outputs.tag }},enable=${{ steps.resolve-tag.outputs.is_release }}
            type=raw,value=latest,enable=${{ steps.resolve-tag.outputs.is_release == 'true' && steps.resolve-tag.outputs.is_prerelease != 'true' }}
            type=raw,value=edge,enable=${{ github.event_name == 'workflow_dispatch' }}
            type=raw,value=sha-${{ github.sha }}-run-${{ github.run_id }}-${{ github.run_attempt }},enable=${{ github.event_name == 'workflow_dispatch' }}
            type=sha,format=short,prefix=sha-,enable=${{ github.event_name != 'workflow_dispatch' }}
          labels: |
            org.opencontainers.image.title=Pullbox
            org.opencontainers.image.description=Modern comic book management and acquisition platform
            org.opencontainers.image.url=https://github.com/${{ github.repository }}
            org.opencontainers.image.source=https://github.com/${{ github.repository }}
            org.opencontainers.image.revision=${{ steps.resolve-sha.outputs.sha }}
            org.opencontainers.image.licenses=GPL-3.0-or-later
            org.opencontainers.image.version=${{ steps.version.outputs.version }}
          annotations: |
            org.opencontainers.image.description=Modern comic book management and acquisition platform for self-hosted environments

  # Build each platform on a separate Docker runner. Digests are pushed without
  # runnable tags so failed validation cannot publish a release.
  build-amd64:
    name: Build AMD64
    runs-on: [self-hosted, Linux, X64, docker]
    needs: [build]
    if: needs.build.outputs.is-release == 'true' || github.event_name == 'workflow_dispatch'
    timeout-minutes: 45
    permissions:
      contents: read
      packages: write
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
      - name: Validate development build attempt
        if: github.event_name == 'workflow_dispatch'
        env:
          BUILD_TAG: ${{ needs.build.outputs.development-tag }}
        run: |
          if [ "${BUILD_TAG}" != "sha-${GITHUB_SHA}-run-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" ]; then
            echo "::error::Development reruns require Re-run all jobs so preparation uses this build attempt."
            exit 1
          fi

      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.build.outputs.build-sha }}

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh base docker

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

      - name: Validate DHI authentication
        env:
          DHI_USERNAME: ${{ secrets.DHI_USERNAME }}
          DHI_TOKEN: ${{ secrets.DHI_TOKEN }}
        run: |
          if [ -z "${DHI_USERNAME}" ] || [ -z "${DHI_TOKEN}" ]; then
            echo "::error::DHI_USERNAME and DHI_TOKEN repository secrets are required."
            exit 1
          fi

      - name: Log in to DHI
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: dhi.io
          username: ${{ secrets.DHI_USERNAME }}
          password: ${{ secrets.DHI_TOKEN }}

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

      - name: Validate Docker Hub authentication
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
        run: |
          if [ -z "${DOCKERHUB_USERNAME}" ] || [ -z "${DOCKERHUB_TOKEN}" ]; then
            echo "::error::Docker Hub credentials are required to publish release images."
            exit 1
          fi

      - name: Log in to Docker Hub
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push AMD64 by digest
        id: build
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: docker/Dockerfile
          platforms: linux/amd64
          outputs: >-
            type=image,"name=${{ env.GHCR_IMAGE }},${{ env.DOCKERHUB_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
          labels: ${{ needs.build.outputs.image-labels }}
          annotations: ${{ needs.build.outputs.image-annotations }}
          build-args: |
            BUILD_DATE=${{ needs.build.outputs.build-date }}
            GIT_SHA=${{ needs.build.outputs.build-sha }}
            GIT_BRANCH=${{ github.ref_name }}
            VERSION=${{ needs.build.outputs.image-version }}
          cache-from: type=gha,scope=pullbox-release-amd64-v1
          cache-to: type=gha,mode=max,scope=pullbox-release-amd64-v1
          provenance: mode=max
          sbom: true

      - name: Validate AMD64 digest in both registries
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          if ! [[ "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "::error::Unexpected AMD64 digest: ${DIGEST}"
            exit 1
          fi
          docker buildx imagetools inspect "${GHCR_IMAGE}@${DIGEST}" > /dev/null
          docker buildx imagetools inspect "${DOCKERHUB_IMAGE}@${DIGEST}" > /dev/null
          mkdir -p "${RUNNER_TEMP}/digests"
          touch "${RUNNER_TEMP}/digests/${DIGEST#sha256:}"

      - name: Upload AMD64 digest
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: release-digest-amd64
          path: ${{ runner.temp }}/digests/*
          if-no-files-found: error
          retention-days: 1

  build-arm64:
    name: Build ARM64
    runs-on: [self-hosted, Linux, X64, docker]
    needs: [build]
    if: needs.build.outputs.is-release == 'true' || github.event_name == 'workflow_dispatch'
    timeout-minutes: 60
    permissions:
      contents: read
      packages: write
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
      - name: Validate development build attempt
        if: github.event_name == 'workflow_dispatch'
        env:
          BUILD_TAG: ${{ needs.build.outputs.development-tag }}
        run: |
          if [ "${BUILD_TAG}" != "sha-${GITHUB_SHA}-run-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" ]; then
            echo "::error::Development reruns require Re-run all jobs so preparation uses this build attempt."
            exit 1
          fi

      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.build.outputs.build-sha }}

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh base docker

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

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

      - name: Validate DHI authentication
        env:
          DHI_USERNAME: ${{ secrets.DHI_USERNAME }}
          DHI_TOKEN: ${{ secrets.DHI_TOKEN }}
        run: |
          if [ -z "${DHI_USERNAME}" ] || [ -z "${DHI_TOKEN}" ]; then
            echo "::error::DHI_USERNAME and DHI_TOKEN repository secrets are required."
            exit 1
          fi

      - name: Log in to DHI
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: dhi.io
          username: ${{ secrets.DHI_USERNAME }}
          password: ${{ secrets.DHI_TOKEN }}

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

      - name: Validate Docker Hub authentication
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
        run: |
          if [ -z "${DOCKERHUB_USERNAME}" ] || [ -z "${DOCKERHUB_TOKEN}" ]; then
            echo "::error::Docker Hub credentials are required to publish release images."
            exit 1
          fi

      - name: Log in to Docker Hub
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push ARM64 by digest
        id: build
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: docker/Dockerfile
          platforms: linux/arm64
          outputs: >-
            type=image,"name=${{ env.GHCR_IMAGE }},${{ env.DOCKERHUB_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
          labels: ${{ needs.build.outputs.image-labels }}
          annotations: ${{ needs.build.outputs.image-annotations }}
          build-args: |
            BUILD_DATE=${{ needs.build.outputs.build-date }}
            GIT_SHA=${{ needs.build.outputs.build-sha }}
            GIT_BRANCH=${{ github.ref_name }}
            VERSION=${{ needs.build.outputs.image-version }}
          cache-from: type=gha,scope=pullbox-release-arm64-v1
          cache-to: type=gha,mode=max,scope=pullbox-release-arm64-v1
          provenance: mode=max
          sbom: true

      - name: Validate ARM64 digest in both registries
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          if ! [[ "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "::error::Unexpected ARM64 digest: ${DIGEST}"
            exit 1
          fi
          docker buildx imagetools inspect "${GHCR_IMAGE}@${DIGEST}" > /dev/null
          docker buildx imagetools inspect "${DOCKERHUB_IMAGE}@${DIGEST}" > /dev/null

      - name: Verify ARM64 container security runtime
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          docker run --rm --pull always --platform linux/arm64 -i \
            --entrypoint python "${GHCR_IMAGE}@${DIGEST}" - \
            < scripts/verify_container_security_runtime.py

      - name: Export ARM64 digest
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          mkdir -p "${RUNNER_TEMP}/digests"
          touch "${RUNNER_TEMP}/digests/${DIGEST#sha256:}"

      - name: Upload ARM64 digest
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: release-digest-arm64
          path: ${{ runner.temp }}/digests/*
          if-no-files-found: error
          retention-days: 1

  # Scan and smoke-test the AMD64 digest as soon as it is available. This runs
  # concurrently with the longer QEMU-backed ARM64 build.
  validate-amd64:
    name: Validate AMD64 Candidate
    runs-on: [self-hosted, Linux, X64, docker]
    needs: [build, build-amd64]
    timeout-minutes: 25
    permissions:
      contents: read
      packages: read
      security-events: write
    env:
      IMAGE_REF: ghcr.io/${{ github.repository }}@${{ needs.build-amd64.outputs.digest }}
      LOCAL_IMAGE: pullbox:release-amd64-${{ github.run_id }}
      SMOKE_CONTAINER: pullbox-release-smoke-${{ github.run_id }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.build.outputs.build-sha }}

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh base docker

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

      - name: Pull candidate image
        run: |
          docker pull "${IMAGE_REF}"
          docker tag "${IMAGE_REF}" "${LOCAL_IMAGE}"

      - name: Verify container security runtime
        run: |
          docker run --rm -i --entrypoint python "${LOCAL_IMAGE}" - \
            < scripts/verify_container_security_runtime.py

      - name: Run Grype scan
        uses: anchore/scan-action@27805bf3b4e84b4a5c980df22ed233c00390a439 # v7.4.2
        id: scan
        with:
          image: ${{ env.LOCAL_IMAGE }}
          grype-version: v0.110.0
          fail-build: true
          severity-cutoff: high
          output-format: sarif
          config: .grype.yaml

      - name: Upload SARIF to GitHub Security
        if: always()
        continue-on-error: true
        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          sarif_file: ${{ steps.scan.outputs.sarif }}
          category: container-scan

      - name: Verify packaged static assets
        run: |
          docker run --rm --entrypoint python "${LOCAL_IMAGE}" -c '
          import pullbox.app

          assets = [
              pullbox.app.STATIC_DIR / "css" / "tailwind.css",
              pullbox.app.STATIC_DIR / "js" / "htmx.min.js",
          ]
          missing = [str(asset) for asset in assets if not asset.is_file()]
          if missing:
              raise SystemExit("Missing packaged static assets: " + ", ".join(missing))
          print("Packaged static assets verified")
          '

      - name: Start container
        run: |
          docker run -d \
            --name "${SMOKE_CONTAINER}" \
            -p 127.0.0.1::8585 \
            -e PULLBOX_SECRET_KEY=smoke-test-secret-key-for-docker-ci \
            -e PULLBOX_LOG_LEVEL=WARNING \
            "${LOCAL_IMAGE}"
          smoke_port=$(docker port "${SMOKE_CONTAINER}" 8585/tcp | awk -F: 'NR == 1 { print $NF }')
          if [ -z "${smoke_port}" ]; then
            echo "::error::Could not determine Pullbox smoke-test port."
            docker port "${SMOKE_CONTAINER}" || true
            exit 1
          fi
          echo "PULLBOX_SMOKE_URL=http://127.0.0.1:${smoke_port}" >> "$GITHUB_ENV"

      - name: Wait for healthy
        run: |
          for i in $(seq 1 30); do
            if curl -sf "${PULLBOX_SMOKE_URL}/ping" > /dev/null 2>&1; then
              echo "Container healthy after ${i}s"
              exit 0
            fi
            sleep 1
          done
          echo "::error::Container failed to become healthy"
          docker logs "${SMOKE_CONTAINER}"
          exit 1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_DEFAULT }}

      - name: Setup runner-local test venv
        run: .github/scripts/setup-runner-venv.sh "dev,e2e"

      - name: Install Playwright browsers
        run: playwright install chromium

      - name: Python preflight
        run: .github/scripts/preflight-runner.sh python

      - name: Run smoke tests
        env:
          PULLBOX_SMOKE_TEST: "true"
        run: |
          pytest tests/e2e/test_smoke.py \
            -v \
            --base-url "${PULLBOX_SMOKE_URL}"

      - name: Upload smoke traces
        if: failure() || cancelled()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: smoke-test-traces
          path: test-results/smoke/
          if-no-files-found: ignore
          retention-days: 7

      - name: Container logs on failure
        if: failure() || cancelled()
        run: docker logs "${SMOKE_CONTAINER}"

      - name: Cleanup local container and image
        if: always()
        run: |
          docker rm -f "${SMOKE_CONTAINER}" || true
          docker image rm "${LOCAL_IMAGE}" || true

  # Development manifests receive staging tags only. Edge is promoted by sign.
  push:
    name: Publish Multi-Arch Manifests
    runs-on: ubuntu-latest
    needs: [build, build-amd64, build-arm64, validate-amd64]
    if: needs.build.outputs.is-release == 'true' || github.event_name == 'workflow_dispatch'
    timeout-minutes: 20
    permissions:
      contents: read
      packages: write
    outputs:
      image-digest: ${{ steps.inspect.outputs.digest }}
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.build.outputs.build-sha }}

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

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

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

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

      - name: Validate Docker Hub authentication
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
        run: |
          if [ -z "${DOCKERHUB_USERNAME}" ] || [ -z "${DOCKERHUB_TOKEN}" ]; then
            echo "::error::Docker Hub credentials are required to publish release images."
            exit 1
          fi

      - name: Log in to Docker Hub
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Publish GHCR multi-platform manifest
        env:
          TAGS: ${{ github.event_name == 'workflow_dispatch' && needs.build.outputs.candidate-tags || needs.build.outputs.image-tags }}
        working-directory: ${{ runner.temp }}/digests
        run: |
          sources=()
          for digest_file in *; do
            sources+=("${GHCR_IMAGE}@sha256:${digest_file}")
          done
          if [ "${#sources[@]}" -ne 2 ]; then
            echo "::error::Expected two platform digests, found ${#sources[@]}."
            exit 1
          fi

          tag_args=()
          while IFS= read -r tag; do
            if [[ "${tag}" == "${GHCR_IMAGE}:"* ]]; then
              tag_args+=(--tag "${tag}")
            fi
          done <<< "${TAGS}"
          if [ "${#tag_args[@]}" -eq 0 ]; then
            echo "::error::No GHCR release tags were generated."
            exit 1
          fi

          docker buildx imagetools create \
            --annotation "index:org.opencontainers.image.description=Modern comic book management and acquisition platform for self-hosted environments" \
            "${tag_args[@]}" \
            "${sources[@]}"

      - name: Publish Docker Hub multi-platform manifest
        env:
          TAGS: ${{ github.event_name == 'workflow_dispatch' && needs.build.outputs.candidate-tags || needs.build.outputs.image-tags }}
        working-directory: ${{ runner.temp }}/digests
        run: |
          sources=()
          for digest_file in *; do
            sources+=("${DOCKERHUB_IMAGE}@sha256:${digest_file}")
          done

          tag_args=()
          while IFS= read -r tag; do
            if [[ "${tag}" == "${DOCKERHUB_IMAGE}:"* ]]; then
              tag_args+=(--tag "${tag}")
            fi
          done <<< "${TAGS}"
          if [ "${#tag_args[@]}" -eq 0 ]; then
            echo "::error::No Docker Hub release tags were generated."
            exit 1
          fi

          docker buildx imagetools create \
            --annotation "index:org.opencontainers.image.description=Modern comic book management and acquisition platform for self-hosted environments" \
            "${tag_args[@]}" \
            "${sources[@]}"

      - name: Validate pushed image metadata
        id: inspect
        env:
          TAGS: ${{ github.event_name == 'workflow_dispatch' && needs.build.outputs.candidate-tags || needs.build.outputs.image-tags }}
        run: |
          GHCR_TAG=$(printf '%s\n' "${TAGS}" | awk -v prefix="${GHCR_IMAGE}:" 'index($0, prefix) == 1 { print; exit }')
          if [ -z "${GHCR_TAG}" ]; then
            echo "::error::Unable to resolve a published GHCR tag."
            exit 1
          fi
          TAG_SUFFIX=${GHCR_TAG#${GHCR_IMAGE}:}
          DOCKERHUB_TAG="${DOCKERHUB_IMAGE}:${TAG_SUFFIX}"

          docker buildx imagetools inspect "${GHCR_TAG}" > ghcr-inspect.txt
          docker buildx imagetools inspect "${DOCKERHUB_TAG}" > dockerhub-inspect.txt
          docker buildx imagetools inspect "${GHCR_TAG}" --raw > ghcr-index.json
          docker buildx imagetools inspect "${DOCKERHUB_TAG}" --raw > dockerhub-index.json

          GHCR_DIGEST=$(awk '$1 == "Digest:" { print $2; exit }' ghcr-inspect.txt)
          DOCKERHUB_DIGEST=$(awk '$1 == "Digest:" { print $2; exit }' dockerhub-inspect.txt)
          if ! [[ "${GHCR_DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "::error::Unexpected GHCR manifest digest: ${GHCR_DIGEST}"
            exit 1
          fi
          if [ "${GHCR_DIGEST}" != "${DOCKERHUB_DIGEST}" ]; then
            echo "::error::Published registry digests differ: GHCR=${GHCR_DIGEST} DockerHub=${DOCKERHUB_DIGEST}"
            exit 1
          fi
          echo "digest=${GHCR_DIGEST}" >> "$GITHUB_OUTPUT"

          python3 - <<'PY'
          import json
          import sys

          expected_description = (
              "Modern comic book management and acquisition platform for "
              "self-hosted environments"
          )
          expected_platforms = {"linux/amd64", "linux/arm64"}

          for registry, path in [
              ("GHCR", "ghcr-index.json"),
              ("Docker Hub", "dockerhub-index.json"),
          ]:
              with open(path, encoding="utf-8") as handle:
                  index = json.load(handle)

              annotations = index.get("annotations") or {}
              if annotations.get("org.opencontainers.image.description") != expected_description:
                  print(f"{registry}: missing OCI index description annotation.", file=sys.stderr)
                  sys.exit(1)

              manifests = index.get("manifests") or []
              platforms = {
                  f"{(manifest.get('platform') or {}).get('os')}/"
                  f"{(manifest.get('platform') or {}).get('architecture')}"
                  for manifest in manifests
                  if manifest.get("platform")
              }
              if not expected_platforms.issubset(platforms):
                  missing = expected_platforms - platforms
                  print(f"{registry}: missing runnable platforms: {missing}", file=sys.stderr)
                  sys.exit(1)

              attestations = sum(
                  1
                  for manifest in manifests
                  if (manifest.get("annotations") or {}).get("vnd.docker.reference.type")
                  == "attestation-manifest"
              )
              if attestations == 0:
                  print(f"{registry}: missing SBOM/provenance attestations.", file=sys.stderr)
                  sys.exit(1)
          PY

      - name: Verify published platform security runtimes
        env:
          DIGEST: ${{ steps.inspect.outputs.digest }}
        run: |
          for platform in linux/amd64 linux/arm64; do
            echo "Verifying container security runtime for ${platform}"
            # The classic Docker image store cannot retain two platform
            # selections under the same multi-platform digest reference.
            docker image rm --force "${GHCR_IMAGE}@${DIGEST}" > /dev/null 2>&1 || true
            docker run --rm --pull always --platform "${platform}" -i \
              --entrypoint python "${GHCR_IMAGE}@${DIGEST}" - \
              < scripts/verify_container_security_runtime.py
          done

      - name: Summary
        env:
          TAGS: ${{ github.event_name == 'workflow_dispatch' && needs.build.outputs.candidate-tags || needs.build.outputs.image-tags }}
        run: |
          {
            echo "## Docker Images Published"
            echo ""
            echo "**Digest:** \`${{ steps.inspect.outputs.digest }}\`"
            echo ""
            echo "**Tags:**"
            echo '```'
            echo "${TAGS}"
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

  sign:
    name: Sign Published Images
    runs-on: ubuntu-latest
    needs: [build, push]
    if: needs.build.outputs.is-release == 'true' || github.event_name == 'workflow_dispatch'
    timeout-minutes: 20
    permissions:
      contents: read
      actions: read
      checks: read
      id-token: write
      packages: write
    steps:
      - name: Checkout
        if: github.event_name == 'workflow_dispatch'
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.build.outputs.build-sha }}

      - name: Set up Docker Buildx
        if: github.event_name == 'workflow_dispatch'
        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

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

      - name: Validate Docker Hub authentication
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
        run: |
          if [ -z "${DOCKERHUB_USERNAME}" ] || [ -z "${DOCKERHUB_TOKEN}" ]; then
            echo "::error::Docker Hub credentials are required to sign release images."
            exit 1
          fi

      - name: Log in to Docker Hub
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

      - name: Sign published image digests
        env:
          DIGEST: ${{ needs.push.outputs.image-digest }}
        run: |
          if [ -z "${DIGEST}" ]; then
            echo "::error::Push job did not return a digest to sign."
            exit 1
          fi
          cosign sign --yes "${GHCR_IMAGE}@${DIGEST}"
          cosign sign --yes "${DOCKERHUB_IMAGE}@${DIGEST}"

      - name: Verify published image signatures
        env:
          DIGEST: ${{ needs.push.outputs.image-digest }}
          CERTIFICATE_IDENTITY: https://github.com/${{ github.workflow_ref }}
          CERTIFICATE_OIDC_ISSUER: https://token.actions.githubusercontent.com
        run: |
          verify_image_signature() {
            local image_ref="$1"
            local label="$2"
            local attempt
            local max_attempts=6

            for attempt in $(seq 1 "${max_attempts}"); do
              if cosign verify \
                --certificate-identity "${CERTIFICATE_IDENTITY}" \
                --certificate-oidc-issuer "${CERTIFICATE_OIDC_ISSUER}" \
                "${image_ref}"; then
                return 0
              fi
              if [ "${attempt}" -eq "${max_attempts}" ]; then
                echo "::error::Signature for ${label} was not discoverable after ${max_attempts} attempts."
                return 1
              fi
              echo "::notice::Signature for ${label} was not discoverable yet; retrying in 10 seconds (${attempt}/${max_attempts})."
              sleep 10
            done
          }

          verify_image_signature "${GHCR_IMAGE}@${DIGEST}" "GHCR"
          verify_image_signature "${DOCKERHUB_IMAGE}@${DIGEST}" "Docker Hub"

      - name: Recheck development validation before promotion
        if: github.event_name == 'workflow_dispatch'
        env:
          GH_TOKEN: ${{ github.token }}
        run: python3 .github/scripts/validate-development-image.py

      - name: Promote verified development image
        if: github.event_name == 'workflow_dispatch'
        env:
          DIGEST: ${{ needs.push.outputs.image-digest }}
          TAGS: ${{ needs.build.outputs.image-tags }}
          BUILD_TAG: ${{ needs.build.outputs.development-tag }}
        run: |
          if ! [[ "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "::error::Cannot promote an invalid image digest."
            exit 1
          fi
          if [ "${BUILD_TAG}" != "sha-${GITHUB_SHA}-run-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" ]; then
            echo "::error::Development reruns require Re-run all jobs; retained preparation outputs cannot be promoted."
            exit 1
          fi
          for registry in "${GHCR_IMAGE}" "${DOCKERHUB_IMAGE}"; do
            tag_args=()
            while IFS= read -r tag; do
              if [[ "${tag}" == "${registry}:"* ]]; then
                suffix=${tag#${registry}:}
                if [ "${suffix}" != "edge" ] && [ "${suffix}" != "${BUILD_TAG}" ]; then
                  echo "::error::Unexpected development image tag."
                  exit 1
                fi
                tag_args+=(--tag "${tag}")
              fi
            done <<< "${TAGS}"
            if [ "${#tag_args[@]}" -ne 4 ]; then
              echo "::error::Expected edge and a run-specific SHA tag for each registry."
              exit 1
            fi
            # A single index source with no annotations is a carbon copy: its
            # digest, SBOM/provenance, and the verified signature remain intact.
            docker buildx imagetools create "${tag_args[@]}" "${registry}@${DIGEST}"
            for tag in "${registry}:edge" "${registry}:${BUILD_TAG}"; do
              published=$(docker buildx imagetools inspect "${tag}" --format '{{json .Manifest}}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["digest"])')
              if [ "${published}" != "${DIGEST}" ]; then
                echo "::error::Promoted development tag does not match the signed digest."
                exit 1
              fi
            done
          done

      - name: Write release image digest artifact
        env:
          DIGEST: ${{ needs.push.outputs.image-digest }}
          TAG: ${{ needs.build.outputs.release-tag }}
        run: |
          if ! [[ "${DIGEST}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
            echo "::error::Unexpected release image digest format: ${DIGEST}"
            exit 1
          fi
          if [ "${{ needs.build.outputs.is-release }}" = "true" ] && ! [[ "${TAG}" =~ ^v.+ ]]; then
            echo "::error::Release image digest artifact requires the triggering release tag."
            exit 1
          fi

          mkdir -p "${RUNNER_TEMP}/release-image-digest"
          printf '%s\n' "${DIGEST}" > "${RUNNER_TEMP}/release-image-digest/digest.txt"
          printf '%s\n' "${TAG}" > "${RUNNER_TEMP}/release-image-digest/tag.txt"

      - name: Upload release image digest artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: release-image-digest
          path: ${{ runner.temp }}/release-image-digest/
          retention-days: 30

      - name: Summary
        env:
          TAGS: ${{ needs.build.outputs.image-tags }}
          BUILD_SHA: ${{ needs.build.outputs.build-sha }}
        run: |
          {
            echo "## Docker Images Signed"
            echo ""
            echo "**Digest:** \`${{ needs.push.outputs.image-digest }}\`"
            echo "**Source commit:** \`${BUILD_SHA}\`"
            echo ""
            echo "**Signing:** Keyless Sigstore/Cosign signatures verified for GHCR and Docker Hub."
            echo ""
            echo "**Published tags:**"
            echo '```'
            echo "${TAGS}"
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"