docker-build-push.yml

name: Docker Build and Push

on:
  push:
    branches:
      - main
      - 'feat/**'
      - 'fix/**'
  # Version and latest tags are published ONLY from a release: a branch push
  # (including any PR merge to main) must never overwrite a pinned version tag
  # or move latest. main pushes publish the mutable "main" tag; feature/fix
  # branches publish "dev"; both always publish an immutable sha- tag.
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      version:
        description: 'Version tag (e.g., 0.9.41 - no v prefix)'
        required: true
        type: string
      publish_latest:
        description: 'Also move the latest tag to this version (set by the release chain; leave false for backfills of old versions)'
        required: false
        default: false
        type: boolean
      variant:
        description: 'Rebuild one image variant instead of all three. Use this when a single leg failed beside two that already published: re-running all of them would re-push version tags the Docker Hub mirror has frozen, and buildx exports every tag in one step, so one rejected tag fails the whole job.'
        required: false
        default: all
        type: choice
        options:
          - all
          - debian
          - alpine
          - alpine-slim

# Cancel an in-progress build when a newer commit is pushed to the same ref,
# so rapid pushes to a feature/fix branch don't stack multi-arch builds.
concurrency:
  group: docker-build-${{ github.ref }}
  cancel-in-progress: true

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository_owner }}/${{ github.event.repository.name }}

jobs:
  # Everything that is the same for all three image variants, resolved once:
  # the gates, the version, the platform list and whether the Docker Hub mirror
  # is in play. The build job below fans out over the variants and would
  # otherwise run ESLint and tsc three times on one commit and ask
  # distribution/channels.yaml the same question three times.
  prepare:
    # Product releases only: chart releases (libredb-studio-<chart-version>)
    # are published by helm-release.yml and must not feed this pipeline. On the
    # first job, so a chart release skips the whole graph rather than each job.
    if: github.event_name != 'release' || !startsWith(github.event.release.tag_name, 'libredb-studio-')
    name: Prepare
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    outputs:
      version: ${{ steps.extract-version.outputs.version }}
      platforms: ${{ steps.platforms.outputs.list }}
      dockerhub: ${{ steps.dockerhub.outputs.enabled }}
      variants: ${{ steps.variants.outputs.matrix }}

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: "1.4.4"

      - name: Install dependencies
        uses: ./.github/actions/bun-install

      - name: Run ESLint
        run: bun run lint

      - name: Run TypeScript type check
        run: bun run typecheck
        env:
          # The whole-tree type check peaks near Node's default heap of about 4 GB
          # on this runner, so it raises the heap as ci.yml does
          # (tests/unit/ci-node-heap.test.ts).
          NODE_OPTIONS: --max-old-space-size=6144

      - name: Extract version from package.json or branch name
        id: extract-version
        # Event payload values go through env (never inline ${{ }} in run:) so a
        # crafted tag name or dispatch input cannot inject into the shell.
        env:
          EVENT_NAME: ${{ github.event_name }}
          INPUT_VERSION: ${{ github.event.inputs.version }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: |
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            VERSION="$INPUT_VERSION"
          else
            VERSION=$(bun -e "console.log(require('./package.json').version)")
          fi
          if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z][0-9A-Za-z.-]*)?$'; then
            echo "Version '$VERSION' is not a valid semver (no v prefix) - refusing to tag images" >&2
            exit 1
          fi
          if [ "$EVENT_NAME" = "release" ] && [ "$RELEASE_TAG" != "$VERSION" ]; then
            echo "Release tag '$RELEASE_TAG' does not match package.json version '$VERSION' - refusing to publish mismatched image tags" >&2
            exit 1
          fi
          echo "version=${VERSION}" >> $GITHUB_OUTPUT
          echo "Version: ${VERSION}"

      - name: Resolve build platforms
        id: platforms
        # arm64 has no native runner in this job, so buildx emulates it through
        # QEMU: native module compilation in the deps stage plus a full
        # `next build` run under emulation, which is most of this job's runtime.
        # A feature-branch push only produces the mutable "dev" tag, consumed by
        # the amd64 Channel E2E job below and nothing else, so paying for arm64
        # on every commit of a PR buys nothing. main, releases and manual
        # dispatches (the release chain) always build the full manifest.
        # Single source of truth: the QEMU step and the build step below both
        # read this output, so they cannot drift into "two arches, no emulator".
        env:
          # Via env, not inline interpolation: a branch name reaches this step
          # and git allows characters a shell would reinterpret.
          EVENT_NAME: ${{ github.event_name }}
          REF: ${{ github.ref }}
        run: |
          if [ "$EVENT_NAME" = "push" ] && [ "$REF" != "refs/heads/main" ]; then
            echo "list=linux/amd64" >> "$GITHUB_OUTPUT"
          else
            echo "list=linux/amd64,linux/arm64" >> "$GITHUB_OUTPUT"
          fi

      # The image variants, and the one place they are listed (#840). The build
      # and Channel E2E jobs both consume this output, so they cannot drift into
      # "built three, browser-tested one".
      #
      # A table in a script rather than a literal `strategy.matrix`, for one
      # reason: a workflow_dispatch may ask for a single variant, and GitHub
      # cannot filter a literal matrix by an input.
      # tests/unit/packaging-image-variants.test.ts reads this table back out and
      # checks it against the Dockerfiles at the repo root.
      - name: Resolve the variant matrix
        id: variants
        env:
          # Empty on every event except workflow_dispatch, where the input
          # defaults to "all".
          REQUESTED: ${{ inputs.variant }}
        run: |
          set -euo pipefail
          VARIANTS='[{"variant":"debian","dockerfile":"Dockerfile","suffix":""},{"variant":"alpine","dockerfile":"Dockerfile.alpine","suffix":"-alpine"},{"variant":"alpine-slim","dockerfile":"Dockerfile.alpine-slim","suffix":"-alpine-slim"}]'
          if [ -z "${REQUESTED:-}" ] || [ "$REQUESTED" = "all" ]; then
            selected="$VARIANTS"
          else
            selected=$(printf '%s' "$VARIANTS" | jq -c --arg v "$REQUESTED" '[.[] | select(.variant == $v)]')
            # A typo must stop the run rather than build nothing and report success.
            if [ "$(printf '%s' "$selected" | jq 'length')" -ne 1 ]; then
              echo "Unknown variant '$REQUESTED' - expected all, debian, alpine or alpine-slim" >&2
              exit 1
            fi
          fi
          printf 'matrix={"include":%s}\n' "$selected" >> "$GITHUB_OUTPUT"
          echo "Building: $(printf '%s' "$selected" | jq -r '[.[].variant] | join(", ")')"

      # Docker Hub is an optional secondary mirror for discoverability. It is
      # only used when DOCKER_HUB_TOKEN is configured (so forks without the
      # secret still build/push to GHCR cleanly).
      - name: Check Docker Hub availability
        id: dockerhub
        env:
          DOCKER_HUB_TOKEN: ${{ secrets.DOCKER_HUB_TOKEN }}
        run: |
          # Two gates: the secret says CI *can* push, update.ci_enabled in
          # distribution/channels.yaml says it *should*. Read here rather than
          # in the build job because this one already has the dependencies
          # installed - and an unreadable inventory leaves the mirror off
          # instead of failing the canonical GHCR publish alongside it.
          ci_enabled=$(node scripts/distribution-check.mjs --ci-enabled docker-hub-mirror 2>/dev/null || echo unresolved)
          if [ "$ci_enabled" != "true" ]; then
            echo "enabled=false" >> "$GITHUB_OUTPUT"
            echo "::notice::docker-hub-mirror update.ci_enabled is '$ci_enabled' in distribution/channels.yaml - skipping the Docker Hub mirror"
          elif [ -n "$DOCKER_HUB_TOKEN" ]; then
            echo "enabled=true" >> "$GITHUB_OUTPUT"
          else
            echo "enabled=false" >> "$GITHUB_OUTPUT"
          fi

  # One job per published variant, in parallel (issue #840). Three files rather
  # than one ARG-interpolated FROM: Dependabot's docker ecosystem cannot follow
  # an interpolated base tag, and the Alpine variants exist for their CVE
  # posture, so losing base bumps would cost them the reason they are here.
  #
  # `fail-fast: false` on purpose: an -alpine-slim that will not build must not
  # cancel the default image every user pulls.
  #
  # The matrix comes from `prepare` so that a workflow_dispatch can rebuild one
  # variant on its own; tests/unit/packaging-image-variants.test.ts asserts the
  # table it is built from lists every Dockerfile at the repo root, so a fourth
  # variant cannot land unpublished.
  build-and-push:
    needs: prepare
    name: Build and Push (${{ matrix.variant }})
    runs-on: ubuntu-latest
    timeout-minutes: 60
    permissions:
      contents: read
      packages: write
      # SLSA build provenance for the image (issue #123). Separate from the
      # inline provenance buildx attaches to the manifest: that one is
      # unsigned, this one is signed with the job's GitHub OIDC identity and
      # verifiable with `gh attestation verify oci://...`.
      id-token: write
      attestations: write
    outputs:
      version: ${{ needs.prepare.outputs.version }}
      image: ${{ steps.meta.outputs.tags }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.prepare.outputs.variants) }}

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6

      - name: Set up QEMU for multi-platform builds
        if: contains(needs.prepare.outputs.platforms, 'arm64')
        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0

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

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GHCR_PAT || secrets.GITHUB_TOKEN }}

      - name: Log in to Docker Hub
        if: needs.prepare.outputs.dockerhub == 'true'
        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
        with:
          username: ${{ vars.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_TOKEN }}

      - name: Prepare image name (lowercase)
        id: image
        run: |
          IMAGE_NAME_LOWER=$(echo "${{ env.IMAGE_NAME }}" | tr '[:upper:]' '[:lower:]')
          echo "name=${IMAGE_NAME_LOWER}" >> $GITHUB_OUTPUT
          echo "Image name (lowercase): ${IMAGE_NAME_LOWER}"

      # Build the list of target images. GHCR is always included; Docker Hub
      # (docker.io/<DOCKER_HUB_ORGANIZATION>/<repo>) is added only when enabled.
      #
      # The namespace is NOT the login user. `libredb` was a Docker Hub user
      # account until 2026-09-01 and one variable answered both questions; the
      # conversion to an organization split them, because an organization cannot
      # sign in. DOCKER_HUB_USERNAME is now the owner who logs in, and the image
      # must still be published under the organization everyone pulls from.
      # Using the login name here does not fail - it publishes to a real
      # repository nobody reads while the mirror goes stale.
      - name: Compose registry image list
        id: images
        env:
          GHCR_IMAGE: ${{ env.REGISTRY }}/${{ steps.image.outputs.name }}
          REPO_NAME: ${{ steps.image.outputs.name }}
          DH_ENABLED: ${{ needs.prepare.outputs.dockerhub }}
          DH_ORGANIZATION: ${{ vars.DOCKER_HUB_ORGANIZATION }}
        run: |
          IMAGES="$GHCR_IMAGE"
          if [ "$DH_ENABLED" = "true" ] && [ -n "$DH_ORGANIZATION" ]; then
            SHORT_NAME="${REPO_NAME##*/}"
            IMAGES="$(printf '%s\ndocker.io/%s/%s' "$IMAGES" "$DH_ORGANIZATION" "$SHORT_NAME")"
          fi
          {
            echo "list<<EOF"
            printf '%s\n' "$IMAGES"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"
          echo "Target images:"
          printf '%s\n' "$IMAGES"

      - name: Extract metadata for Docker
        id: meta
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ steps.images.outputs.list }}
          # The variant suffix is written into each tag rather than set through
          # the action's `flavor`, which would have to carry an empty suffix for
          # the default image. `:0.16.2`, `:0.16.2-alpine`, `:0.16.2-alpine-slim`
          # and the same three for latest/main/dev and the immutable sha- tag.
          tags: |
            type=raw,value=${{ needs.prepare.outputs.version }}${{ matrix.suffix }},enable=${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' }}
            # latest moves on a real release event, or on the release chain's
            # dispatch (publish_latest=true, pinned to the release tag ref).
            # A plain manual dispatch (backfilling an old version) must never
            # move latest - the 0.9.46 chain shipped with latest stuck on the
            # previous release because dispatch could not move it at all.
            # Keep this "release context" condition in step with the
            # dispatch-helm-release job's if: below - if they drift, the
            # chart dispatch and the latest tag disagree on what a release is.
            type=raw,value=latest${{ matrix.suffix }},enable=${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.publish_latest == true) }}
            type=raw,value=main${{ matrix.suffix }},enable=${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
            type=raw,value=dev${{ matrix.suffix }},enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
            type=sha,prefix=sha-,suffix=${{ matrix.suffix }}

      - name: Build and push Docker image
        id: build
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: .
          file: ${{ matrix.dockerfile }}
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          # Scoped per variant: the three builds share almost no layers (glibc
          # against musl, three different runner bases), so one scope would have
          # them evicting each other's cache on every run.
          cache-from: type=gha,scope=${{ matrix.variant }}
          cache-to: type=gha,mode=max,scope=${{ matrix.variant }}
          platforms: ${{ needs.prepare.outputs.platforms }}
          build-args: |
            JWT_SECRET_BUILD=build-time-placeholder-secret-32ch
            ADMIN_PASSWORD_BUILD=build
            USER_PASSWORD_BUILD=build

      # Release-context builds only, matching the version-tag condition above:
      # branch pushes move the mutable main/dev tags, and signing an image no
      # user installs only adds noise to the transparency log.
      #
      # Subject is the digest, never a tag - latest/main move, and the manifest
      # list digest is the image's only stable identity. The Docker Hub mirror
      # publishes the same digest, so `gh attestation verify` resolves it there
      # too; GHCR is the name recorded because it is the canonical registry.
      #
      # push-to-registry stays off on purpose: writing an OCI referrer back to
      # GHCR is a second failure mode on the release path, and the attestation
      # is already retrievable from GitHub without it.
      - name: Attest the pushed image
        if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
        with:
          subject-name: ${{ env.REGISTRY }}/${{ steps.image.outputs.name }}
          subject-digest: ${{ steps.build.outputs.digest }}

      - name: Generate build summary
        run: |
          echo "## 🚀 Docker Build Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Branch:** ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
          echo "**Variant:** ${{ matrix.variant }} (${{ matrix.dockerfile }})" >> $GITHUB_STEP_SUMMARY
          echo "**Version:** ${{ needs.prepare.outputs.version }}" >> $GITHUB_STEP_SUMMARY
          echo "**Docker Hub mirror:** ${{ needs.prepare.outputs.dockerhub }}" >> $GITHUB_STEP_SUMMARY
          echo "**Platforms:** ${{ needs.prepare.outputs.platforms }}" >> $GITHUB_STEP_SUMMARY
          echo "**Image:** ${{ steps.image.outputs.name }}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Tags:" >> $GITHUB_STEP_SUMMARY
          echo '```' >> $GITHUB_STEP_SUMMARY
          echo "${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
          echo '```' >> $GITHUB_STEP_SUMMARY


  # Browser E2E of the embedded samples against the image THIS run pushed
  # (docker channel of scripts/channel-embedded-sample-e2e.sh). The image is
  # already on GHCR - this cannot un-push it - but a red run blocks the
  # release chain below and flags broken packaging on branch builds.
  #
  # ONE RUN PER VARIANT, and that is the point of the matrix rather than a
  # convenience. `e2e/embedded-samples.spec.ts` waits on `.monaco-editor`, and
  # the first -alpine-slim build shipped an image that booted, served /login and
  # seeded its sample database with no query editor at all: every check a
  # single-image pipeline runs was green. A packaging trade only stays a trade
  # if a browser confirms what survived it.
  channel-e2e:
    name: Channel E2E (docker, ${{ matrix.variant }})
    needs: [prepare, build-and-push]
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.prepare.outputs.variants) }}
    # Deliberately NOT run inside Playwright's container image (unlike the two
    # jobs in ci.yml): this channel drives `docker pull` / `docker run`, and a
    # container job has no daemon. scripts/channel-embedded-sample-e2e.sh would
    # not fail loudly either - channel_docker() skips when docker is absent,
    # and a directly requested channel that silently disappears is worse than a
    # slow one. So the apt cost is removed here by dropping --with-deps instead.
    permissions:
      contents: read
      packages: read
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6

      - name: Setup Bun
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: "1.4.4"

      - name: Install dependencies
        uses: ./.github/actions/bun-install

      - name: Install Playwright browsers
        # chromium only, and no --with-deps: the ubuntu-latest image already
        # ships Google Chrome and therefore chromium's shared libraries. The
        # apt half of --with-deps was the whole cost here (111 MB from
        # azure.archive.ubuntu.com, 86 minutes when that mirror degraded on
        # 2026-08-19) against 12 seconds of browser download. Webkit is the
        # one that genuinely needs extra packages, and this channel never
        # runs it: playwright.channel.config.ts is a chromium-only project list.
        run: bunx playwright install chromium

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GHCR_PAT || secrets.GITHUB_TOKEN }}

      - name: Run channel E2E against the pushed image
        env:
          REGISTRY_IMAGE: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          COMMIT_SHA: ${{ github.sha }}
          VARIANT_SUFFIX: ${{ matrix.suffix }}
        run: |
          # Same immutable tag the metadata step publishes
          # (type=sha,prefix=sha-,suffix=<variant>).
          IMAGE="$(echo "$REGISTRY_IMAGE" | tr '[:upper:]' '[:lower:]'):sha-$(printf '%s' "$COMMIT_SHA" | cut -c1-7)${VARIANT_SUFFIX}"
          docker pull "$IMAGE"
          bash scripts/channel-embedded-sample-e2e.sh docker "$IMAGE"

  dispatch-helm-release:
    # The chart deploys the image this run just published, so helm-release
    # runs only AFTER a successful publish: the version-bump merge's own
    # helm-release run ends as a no-op at its image gate, and this dispatch
    # re-triggers it now that the image exists. Release context only -
    # main/dev branch builds must not publish charts - and a failed build
    # dispatches nothing, so the chart correctly stays unpublished. Separate
    # job so actions:write is never granted to ordinary branch builds, and
    # the dispatch targets THIS run's ref so the chart is released from the
    # same commit as the image (a main dispatch could pick up a newer,
    # not-yet-built chart). The if: below is the same "release context"
    # condition as the latest-tag enable in the metadata step above - keep
    # the two in step. channel-e2e gates the dispatch: a release image that
    # fails the packaged-artifact browser test must not fan out to the chart.
    name: Dispatch Helm chart release
    needs: [build-and-push, channel-e2e]
    # The variant clause is the recovery path's guard, not part of the release
    # condition: a dispatch that rebuilt ONE leg beside two that already
    # published must not re-release a chart whose contents did not change, and
    # #167 then blocks the retry a real chart change needs.
    if: >-
      github.event_name == 'release' ||
      (github.event_name == 'workflow_dispatch' && inputs.publish_latest == true &&
       (inputs.variant == '' || inputs.variant == 'all'))
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      actions: write
    steps:
      - name: Dispatch helm-release on this ref
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
          REF: ${{ github.ref }}
        run: |
          set -euo pipefail
          gh workflow run helm-release.yml --ref "$REF"
          echo "Dispatched helm-release on ${REF}."

  dispatch-caprover-fork:
    # The CapRover templates deploy the image this run just published, so their
    # catalog branch is staged only after a successful publish and its channel
    # E2E, and only for a release: a run that moves the latest tags, never a
    # backfill of an old version, and never a prerelease, which the catalog must
    # not default to. Unlike the Helm dispatch above, a single-variant recovery
    # dispatches it too: the leg it rebuilt was the last image missing, and
    # caprover-fork leaves a branch that already holds the same templates alone.
    # Separate job so actions:write is never granted to ordinary branch builds;
    # the dispatch targets THIS run's ref, the release tag, whose templates
    # chart:check holds at the release version.
    name: Dispatch CapRover catalog fork
    needs: [build-and-push, channel-e2e]
    if: >-
      !contains(github.ref, '-') &&
      (github.event_name == 'release' ||
       (github.event_name == 'workflow_dispatch' && inputs.publish_latest == true))
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      actions: write
    steps:
      - name: Dispatch caprover-fork on this ref
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
          REF: ${{ github.ref }}
        run: |
          set -euo pipefail
          gh workflow run caprover-fork.yml --ref "$REF" -f trigger=release
          echo "Dispatched caprover-fork on ${REF}."

  # DOCKERHUB.md is the Docker Hub listing text. The repo keeps it current - the
  # release checklist asks for the engine list to be checked in it alongside
  # README.md - but nothing ever pushed it to the registry, so the listing sat
  # on whatever was there when the repository was created: on 20 Sep 2026 it
  # still advertised `docker pull libredb/libredb-studio:0.12.0` as the
  # pin-an-exact-version example, nine releases after that tag.
  #
  # Same two gates as the mirror push itself: the token says CI *can* reach
  # Docker Hub, update.ci_enabled in distribution/channels.yaml says it
  # *should*. Release context only, so a branch build never rewrites the public
  # page. Not continue-on-error: by the time this runs the images are published
  # and a red job unpublishes nothing, so the only thing a swallowed failure
  # buys is another listing that silently falls behind. The full_description cap
  # (25000 BYTES, measured against the live API, not characters) is held by
  # tests/unit/dockerhub-listing.test.ts, which fails the PR that
  # crosses it rather than the release that follows it.
  sync-dockerhub-description:
    name: Sync Docker Hub description
    needs: [prepare, build-and-push]
    if: >-
      needs.prepare.outputs.dockerhub == 'true' &&
      vars.DOCKER_HUB_ORGANIZATION != '' &&
      (github.event_name == 'release' ||
       (github.event_name == 'workflow_dispatch' && inputs.publish_latest == true))
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
        with:
          persist-credentials: false

      # The npm package headline, so the listing's one-liner and the package's
      # cannot drift apart. Docker Hub caps it at 100 characters; the same test
      # holds that end.
      - name: Read the short description
        id: short
        run: |
          set -euo pipefail
          {
            echo "description<<EOF"
            jq -r '.description' package.json
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Push DOCKERHUB.md to the listing
        uses: peter-evans/dockerhub-description@1b9a80c056b620d92cedb9d9b5a223409c68ddfa # v5.0.0
        with:
          username: ${{ vars.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_TOKEN }}
          repository: ${{ vars.DOCKER_HUB_ORGANIZATION }}/${{ github.event.repository.name }}
          readme-filepath: ./DOCKERHUB.md
          short-description: ${{ steps.short.outputs.description }}
          # Every link in DOCKERHUB.md is already absolute, and the test above
          # keeps it that way, so there is nothing for url completion to rewrite
          # - and its known failure modes on code spans cannot bite.
          enable-url-completion: false