ci(docker): tag-only trigger for prod image build (#1392)

Drop `push: branches: [main]` and the `pull_request:` block from
docker-image.yml so the workflow only fires on `*.*.*` tag pushes
and manual `workflow_dispatch` reruns. Saves Actions minutes — the
multi-arch (amd64 + qemu-emulated arm64) build is the most expensive
job in the matrix and was burning ~8-15 minutes per main-push and
per qualifying PR for floating `:main` / `:sha-<short>` images that
self-hosters don't pull (the docs steer everyone to released semver
tags). The image surface is small + stable, runtime-affecting changes
always ship behind a release tag, and verifying-at-tag is sufficient.

Trade-off the project explicitly accepts: a broken Dockerfile /
entrypoint that landed via a green PR isn't caught by CI until the
next tag push. AGENTS.md documents this — contributors who edit any
file the runtime image bakes in MUST run the local
`docker buildx build --platform linux/amd64,linux/arm64
-f docker/Dockerfile.prod .` command before opening the PR; the
local command IS the per-PR gate.

Companion cleanups so nothing else lies about the trigger surface:

- Drop the `type=ref,event=branch` / `event=pr` / `type=sha` rules
  from docker/metadata-action — those produced the now-defunct
  `:main` and `:sha-<short>` floating tags that won't exist anymore.
- Drop the `if: github.event_name != 'pull_request'` gates from
  the GHCR-login, cosign-installer, and cosign-sign steps — there
  is no PR trigger for them to short-circuit. `push: true` on the
  build-push step too (was conditional, no longer needs to be).
- Update the operator-facing tag table in
  `docs/src/content/docs/getting-started/quickstart-docker.mdx` to
  drop the `:main` and `:sha-<short>` rows + add a paragraph
  pointing self-hosters who want a yet-unreleased fix at a local
  `docker buildx build`.
- Update the Dockerfile's OCI-labels comment to reference
  workflow_dispatch / local builds instead of the gone tag patterns.
- Update AGENTS.md:
  - Quality gates table heading: "seven gates on every PR" →
    "six gates on every PR"; the seventh row is annotated as
    release-only with the contributor-side responsibility.
  - "Keep the docs in sync" row for the prod-docker cluster
    spells out that the gate is release-only and the local
    command is the per-PR check.
  - "Prod Docker image specifics" block rewritten end-to-end
    around the tag-only contract — drops the dead path-filter
    paragraph + the verify-only-PR-build paragraph + the now-
    unnecessary cosign-PR-exemption paragraph.

Stacked on #1391 because the workflow file lives on that branch.

Author: rumblefrog

.github/workflows/docker-image.yml

@@ -2,11 +2,16 @@ name: Docker image
 
 # Build + publish the production image to GHCR (#1381 deliverable 3).
 #
-# Triggers:
-#   - push to main             → :main + :sha-<short>
+# Triggers (deliberately tag-only — see "Why no main / PR triggers"
+# below):
 #   - push to *.*.* tag        → :<version> + :latest + :<major> + :<major>.<minor>
-#   - workflow_dispatch        → manual rerun (same tagging logic; useful
-#                                if a release publish failed midway)
+#   - workflow_dispatch        → manual rerun, dispatched against a tag
+#                                ref to rebuild a published release
+#                                (e.g. if a publish failed midway).
+#                                Dispatching from a non-tag ref is a
+#                                no-op for tagging — metadata-action
+#                                emits an empty tag set and the publish
+#                                step fails loudly.
 #
 # Multi-arch build via docker/build-push-action + buildx + qemu. Both
 # linux/amd64 and linux/arm64 are produced and pushed under a single
@@ -24,61 +29,29 @@ name: Docker image
 # --certificate-oidc-issuer=https://token.actions.githubusercontent.com`
 # without any pre-shared key.
 #
-# Path filter scope (PR trigger only — see MED-6 below for the
-# push-trigger rationale):
-#   - docker/Dockerfile.prod, docker/php/prod-*, docker/apache/sbpp-prod.conf,
-#     docker/php/sb-db.php — every file the runtime image bakes in
-#   - web/health.php — the file the HEALTHCHECK pings
-#   - web/init.php / web/init-recovery.php — the SBPP_CONFIG_PATH
-#     plumbing + install-guard contract the entrypoint relies on
-#   - web/install/includes/sql/** — schema and seed data the entrypoint
-#     loads on first-boot install
-#   - web/includes/Auth/Host.php — the SBPP_TRUSTED_PROXIES gate the
-#     entrypoint's Apache config feeds (CRIT-4)
-#   - web/includes/Telemetry/Telemetry.php — the SBPP_SKIP_TELEMETRY
-#     hook health.php depends on (MED-4)
-#   - composer.json/lock under web/ — vendor dependency churn
-#   - .github/workflows/docker-image.yml — touch-the-workflow trigger
-#
-# MED-6 of the #1381 review: pre-fix, the `push:` block specified
-# `branches`, `tags`, AND `paths` at the same level. GitHub Actions
-# AND-combines them — a tag push only fires when the underlying
-# commit ALSO touches one of the listed paths. Release tags are
-# typically attached to commits that already shipped through `main`
-# (so the paths filter masked the prod-image surface change), which
-# means a release-tag push could silently NOT build the image and
-# `:latest` would lag behind `:main` indefinitely.
-#
-# Fix: drop the `paths` filter from `push:` entirely. Every push to
-# `main` AND every release-tag push triggers a full multi-arch build.
-# Action minutes for tag pushes are unconditional (correct for a
-# release surface); main pushes are rare (PRs aggregate via squash
-# merges) so the per-merge cost is acceptable. The `pull_request:`
-# block keeps its paths filter — PRs that don't touch the image
-# surface still don't rebuild, preserving the per-PR action-minute
-# optimisation that originally motivated the path filter.
+# Why no main / PR triggers:
+# Multi-arch (amd64 + qemu-emulated arm64) image builds are the most
+# expensive job in this repo's CI matrix — roughly 8-15 minutes per
+# run. Pre-fix this workflow ran on every push to main AND every PR
+# touching a long path filter, which on a busy week burned through a
+# disproportionate share of the project's free Actions minutes for
+# images that nobody pulls (the floating `:main` and per-commit
+# `:sha-<short>` tags were nominally documented as "bleeding edge"
+# but had no real consumers; self-hosters all pin to released semver
+# tags per the docs). The image surface is small + stable: changes
+# that affect the runtime contract (Dockerfile, entrypoint, schema
+# files, init bootstrap, health.php, trust-proxy + telemetry hooks)
+# are always shipped behind a release tag, so verifying-at-tag is
+# both sufficient and well-aligned with when self-hosters actually
+# pull a new image. Contributors who edit the Dockerfile / entrypoint
+# locally are expected to run the literal `docker buildx build`
+# command from the AGENTS.md "Quality gates" table to verify before
+# opening a PR.
 
 on:
   push:
-    branches:
-      - main
     tags:
       - '*.*.*'
-  pull_request:
-    paths:
-      - 'docker/Dockerfile.prod'
-      - 'docker/php/prod-*'
-      - 'docker/php/sb-db.php'
-      - 'docker/apache/sbpp-prod.conf'
-      - 'web/composer.json'
-      - 'web/composer.lock'
-      - 'web/health.php'
-      - 'web/init.php'
-      - 'web/init-recovery.php'
-      - 'web/install/includes/sql/**'
-      - 'web/includes/Auth/Host.php'
-      - 'web/includes/Telemetry/Telemetry.php'
-      - '.github/workflows/docker-image.yml'
   workflow_dispatch:
 
 # `packages: write`  — push to GHCR.
@@ -103,8 +76,7 @@ jobs:
       # buildx is the multi-platform driver. qemu provides the cross-arch
       # emulation that lets the amd64 GitHub-hosted runner produce an
       # arm64 image. The cost is roughly +2x build time on the arm64
-      # leg vs native; acceptable for the publish cadence (per-tag +
-      # main pushes only).
+      # leg vs native; acceptable for the release-only publish cadence.
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
         with:
@@ -115,37 +87,35 @@ jobs:
 
       # GHCR push needs the actor's PAT — for actions/github-token, the
       # token's `packages: write` permission is granted by the job-level
-      # `permissions:` block above. Pull-request builds (which never push)
-      # skip login.
+      # `permissions:` block above.
       - name: Log in to GHCR
-        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       # docker/metadata-action computes the tag set from the trigger:
-      #   - main push           → :main, :sha-<short>
       #   - X.Y.Z tag           → :X.Y.Z, :X.Y, :X, :latest
-      #   - PR                  → :pr-<num> (kept locally; not pushed)
-      #   - workflow_dispatch   → :main (treated like a main rerun)
+      #   - workflow_dispatch   → mirrors whatever ref it was dispatched
+      #                            against (typically a tag ref to
+      #                            rebuild a published release; a non-tag
+      #                            dispatch produces an empty tag set
+      #                            and the publish step fails loudly).
       #
-      # The `:latest` tag is gated on `type=semver,pattern={{version}}`
-      # so PR / main / dispatch builds don't accidentally claim it.
+      # The `:latest` tag is gated on `startsWith(github.ref, 'refs/tags/')`
+      # — a workflow_dispatch from a non-tag ref can't accidentally
+      # claim it.
       - name: Compute image metadata (tags + labels)
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=ref,event=branch
-            type=ref,event=pr
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
             type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') }}
-            type=sha,prefix=sha-,format=short
           labels: |
             org.opencontainers.image.title=SourceBans++
             org.opencontainers.image.description=Self-hostable admin / ban / comms management for the Source engine — production image.
@@ -160,41 +130,36 @@ jobs:
       # are persisted in the GitHub Actions cache between runs — buildx
       # keys the cache by the Dockerfile + the build context's hash, so
       # a Composer-only change won't bust the apt-install layer of the
-      # builder stage.
-      #
-      # `push: ${{ github.event_name != 'pull_request' }}` means PR
-      # builds verify-build-only (build runs, but the image stays local
-      # to the runner — no GHCR write). Main / tag / dispatch builds
-      # publish.
+      # builder stage. (Cache hit rate is naturally low on the tag-only
+      # trigger — release tags are rare — but the cost of populating
+      # the cache on a release build is amortised across the next
+      # workflow_dispatch rerun for that tag.)
       - name: Build + push
         id: build
         uses: docker/build-push-action@v6
         with:
           context: .
           file: docker/Dockerfile.prod
           platforms: linux/amd64,linux/arm64
-          push: ${{ github.event_name != 'pull_request' }}
+          push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
           provenance: true
           sbom: true
 
-      # Cosign keyless signing — runs only when we actually pushed.
-      # Each tag the manifest carries gets its own signature recorded
-      # into Rekor. The `cosign sign --yes <ref>@<digest>` form is the
-      # documented best-practice (signs the immutable digest, not the
-      # mutable tag — so a future re-tag doesn't invalidate the
+      # Cosign keyless signing. Each tag the manifest carries gets its
+      # own signature recorded into Rekor. The `cosign sign --yes <ref>@<digest>`
+      # form is the documented best-practice (signs the immutable digest,
+      # not the mutable tag — so a future re-tag doesn't invalidate the
       # signature).
       - name: Install cosign
-        if: github.event_name != 'pull_request'
         uses: sigstore/cosign-installer@v3
         with:
           cosign-release: 'v2.4.1'
 
       - name: Sign image with cosign (keyless)
-        if: github.event_name != 'pull_request'
         env:
           # NIT-1 of the #1381 review: `COSIGN_EXPERIMENTAL=1` was the
           # gate for keyless signing back when it was experimental

AGENTS.md

@@ -57,7 +57,7 @@ code change — never as a follow-up. CI doesn't gate this; it's on you.
 | Change the local dev stack (Docker, db-init, env vars)      | `docker/README.md` first, link from `ARCHITECTURE.md` if it changes the dev mental model |
 | Edit user-facing install/quickstart                         | `docs/src/content/docs/getting-started/quickstart.mdx` (tarball flow) OR `quickstart-docker.mdx` (Docker flow). Keep the `<Tabs syncKey="install-path">` arms in `overview.mdx` + `prerequisites.mdx` consistent across the two paths (the README is a tiny landing page that links to docs — don't grow it back into a manual). |
 | Add or change a wizard step (page handler / View / template / shared helper) | `AGENTS.md` (Install wizard convention block) + the "Edit a step of the install wizard" row in "Where to find what" |
-| Touch `docker/Dockerfile.prod`, `docker/php/prod-*`, `docker/apache/sbpp-prod.conf`, `docker-compose.prod.yml`, `.env.example.prod`, `docker/caddy/Caddyfile.example`, or `web/health.php` | `AGENTS.md` (Quality gates: `docker-image.yml` row; "Where to find what": the "Build / extend the production Docker image" + "Deploy / configure the production Docker stack" rows) + `docs/src/content/docs/getting-started/quickstart-docker.mdx` (the operator-facing doc) + `docker/README.md` (dev-vs-prod pointer). The `Plugin build specifics` block in AGENTS.md has a sibling `Prod Docker image specifics` block — keep them in sync with the workflow's path filter / tag mapping / sign step. |
+| Touch `docker/Dockerfile.prod`, `docker/php/prod-*`, `docker/apache/sbpp-prod.conf`, `docker-compose.prod.yml`, `.env.example.prod`, `docker/caddy/Caddyfile.example`, or `web/health.php` | `AGENTS.md` (Quality gates: `docker-image.yml` row; "Where to find what": the "Build / extend the production Docker image" + "Deploy / configure the production Docker stack" rows) + `docs/src/content/docs/getting-started/quickstart-docker.mdx` (the operator-facing doc) + `docker/README.md` (dev-vs-prod pointer). The `Plugin build specifics` block in AGENTS.md has a sibling `Prod Docker image specifics` block — keep them in sync with the workflow's tag mapping / sign step. The Docker-image gate is **release-only** (fires on `*.*.*` tag pushes + manual `workflow_dispatch` reruns); contributors who edit the Dockerfile / entrypoint MUST run the `docker buildx build` command from the Quality gates row locally before opening the PR — there is no per-PR CI gate to catch a broken image build. |
 | Change a user-facing install / upgrade / troubleshooting flow (PHP or SourceMod version requirements, installer wizard steps, `config.php` behavior, `web/updater/` runner output, plugin `databases.cfg` / `sourcebans.cfg` shape, error messages a self-hoster will see) | The relevant page under `docs/src/content/docs/` (the Starlight site published at sbpp.github.io). |
 | Add or remove a config knob a self-hoster sets (`config.php` keys, `databases.cfg` fields, plugin convars users tune) | `docs/` page that documents that knob, plus the matching `docs/src/content/docs/updating/*.mdx` page if it's a breaking change between releases |
 | Ship a new feature with a self-hoster-visible setup step (Discord forwarder, demos, theming, etc.) | New page or section under the right `docs/` group + sidebar entry in `docs/astro.config.mjs` |
@@ -181,7 +181,10 @@ services:
 
 ## Quality gates
 
-CI runs seven gates on every PR. Match them locally before opening one.
+CI runs six gates on every PR. Match them locally before opening one.
+A seventh gate (the production Docker image) runs **only on release
+tag pushes** — see the row's note + the `Prod Docker image specifics`
+block below for the rationale and the contributor-side responsibility.
 
 | Gate           | Local                                | CI workflow            |
 | -------------- | ------------------------------------ | ---------------------- |
@@ -191,7 +194,7 @@ CI runs seven gates on every PR. Match them locally before opening one.
 | API contract   | `./sbpp.sh composer api-contract`    | `api-contract.yml`     |
 | Playwright E2E | `./sbpp.sh e2e`                      | `e2e.yml`              |
 | Plugin build   | `(cd game/addons/sourcemod/scripting && spcomp -i include sbpp_*.sp)` | `plugin-build.yml`     |
-| Prod Docker image | `docker buildx build --platform linux/amd64,linux/arm64 -f docker/Dockerfile.prod .` | `docker-image.yml` |
+| Prod Docker image (release-only) | `docker buildx build --platform linux/amd64,linux/arm64 -f docker/Dockerfile.prod .` | `docker-image.yml` (tag pushes + `workflow_dispatch` only — no per-PR run; contributor MUST run the local command before merging Dockerfile / entrypoint changes) |
 
 PHPStan specifics:
 
@@ -340,41 +343,57 @@ Plugin build specifics:
 
 Prod Docker image specifics:
 
-- Path-filtered to `docker/Dockerfile.prod`, `docker/php/prod-*`,
-  `docker/apache/sbpp-prod.conf`, `web/composer.{json,lock}`,
-  `web/health.php`, `web/init.php`, `web/init-recovery.php`, and
-  the workflow file itself. A web/-only PR that doesn't touch those
-  files skips the gate (the surface changes constantly; rebuilding
-  the prod image on every PR would burn action minutes for changes
-  the next release cycle picks up anyway). Main and tag pushes
-  always rebuild.
+- **Trigger surface is deliberately narrow: tag pushes + manual
+  `workflow_dispatch` only.** No `push: branches: [main]`, no
+  `pull_request:`. A multi-arch (amd64 + qemu-emulated arm64) build
+  is the most expensive job in this repo's CI matrix (~8-15 minutes
+  per run); pre-narrow this workflow ran on every push to main AND
+  every PR touching a long path filter, burning a disproportionate
+  share of the project's free Actions minutes for floating `:main` /
+  `:sha-<short>` tags that nobody pulls (self-hosters all pin to
+  released semver tags per the docs). The image surface is small +
+  stable — runtime-affecting changes (Dockerfile, entrypoint, schema
+  files, init bootstrap, health.php, trust-proxy + telemetry hooks)
+  always ship behind a release tag, so verifying-at-tag is sufficient
+  AND well-aligned with when self-hosters actually pull a new image.
+  The trade-off the project explicitly accepts: a Dockerfile /
+  entrypoint regression that landed via a green PR isn't caught by
+  CI until the next `*.*.*` tag push. **Contributors who edit any
+  file the runtime image bakes in (Dockerfile, entrypoint, php.ini,
+  Apache conf, sb-db.php, health.php, schema files, init bootstrap,
+  Auth/Host.php, Telemetry.php) MUST run the literal `docker buildx
+  build --platform linux/amd64,linux/arm64 -f docker/Dockerfile.prod .`
+  command from the Quality gates table locally before opening the
+  PR — the local command IS the per-PR gate.**
 - Multi-arch (linux/amd64 + linux/arm64) via `docker/setup-qemu-action@v3`
   + `docker/setup-buildx-action@v3`. The arm64 leg runs under qemu
   on the amd64 GitHub-hosted runner — roughly 2x build time vs
-  native, acceptable for the publish cadence.
-- PR builds are **verify-only** — `push: ${{ github.event_name != 'pull_request' }}`
-  in `build-push-action` runs the build to verify-it-builds without
-  pushing to GHCR. Main / tag / dispatch pushes publish + sign.
-- Tag mapping via `docker/metadata-action@v5`: `main` push →
-  `:main` + `:sha-<short>`; `X.Y.Z` tag → `:X.Y.Z` + `:X.Y` + `:X`
-  + `:latest`. `:latest` is gated on `startsWith(github.ref, 'refs/tags/')`
-  so main pushes can't accidentally claim it.
+  native, acceptable for the release-only publish cadence.
+- Tag mapping via `docker/metadata-action@v5`: `X.Y.Z` tag → `:X.Y.Z`
+  + `:X.Y` + `:X` + `:latest`. `:latest` is gated on
+  `startsWith(github.ref, 'refs/tags/')` so a `workflow_dispatch`
+  from a non-tag ref can't accidentally claim it. There are no
+  rolling `:main` / `:sha-<short>` tags — see the table in
+  `docs/src/content/docs/getting-started/quickstart-docker.mdx`
+  for the operator-facing tag list. A `workflow_dispatch` from a
+  non-tag ref produces an empty tag set and `docker push` fails
+  loudly (the documented "rebuilding a non-released ref isn't a
+  meaningful operation" gate).
 - Sigstore cosign signs each tag against the immutable digest
   (`<image>@<digest>`, not the mutable `<image>:<tag>`) in keyless
   / OIDC mode. The job-level `id-token: write` permission is what
   enables the OIDC token request; without it cosign can't get a
   Fulcio cert and signing fails closed. Verifiers pin both the
   identity (workflow path) and the issuer (GitHub Actions OIDC
   endpoint) — see `docs/src/content/docs/getting-started/quickstart-docker.mdx`
-  for the canonical `cosign verify` command.
-- The cosign step is gated on `github.event_name != 'pull_request'`
-  for the same reason as the push step — PR builds never publish,
-  so there's nothing to sign.
+  for the canonical `cosign verify` command. The cosign step is
+  always-on (no PR exemption is needed — PRs don't trigger the
+  workflow at all under the tag-only contract).
 - No local `./sbpp.sh` wrapper. The dev stack doesn't ship a way
   to invoke `docker buildx` from inside the dev container itself
   (no Docker-in-Docker), and the prod image build is a host-side
-  workflow. Contributors who want to verify a local build run the
-  literal command from the gates table.
+  workflow. Contributors verify a local build with the literal
+  command from the gates table.
 
 ## Conventions