@devopsplaybook.io/common-utils 1.6.0-beta.15.02b378d → 1.7.0-beta.16.179c4ff

package/.github/workflows/reusable-merge-build.yml

@@ -4,17 +4,17 @@ on:
   workflow_call:
     inputs:
       docker_platforms:
-        description: "Docker platforms to build for"
+        description: "Docker platforms, used only by the fallback build when no PR image can be promoted"
         required: false
         type: string
         default: "linux/arm64/v8,linux/amd64"
       node_app_directories:
-        description: "JSON array of Node.js app directories to build, lint, and test"
+        description: "Deprecated and unused. Kept so existing callers stay valid: the merge build runs no build, lint or test."
         required: false
         type: string
         default: ""
       node_version:
-        description: "Node.js version to use"
+        description: "Deprecated and unused. Kept so existing callers stay valid: the merge build runs no Node.js job."
         required: false
         type: string
         default: "22"
@@ -28,84 +28,18 @@ on:
       QUALITY_DASHBOARD_URL:
         required: false
 
-jobs:
-  node-build:
-    if: inputs.node_app_directories != ''
-    strategy:
-      matrix:
-        app: ${{ fromJSON(inputs.node_app_directories) }}
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: ${{ matrix.app }}
-    steps:
-      - uses: actions/checkout@v7
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v7
-        with:
-          node-version: ${{ inputs.node_version }}
-          cache: "npm"
-          cache-dependency-path: ${{ matrix.app }}/package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Test
-        run: npm run test
-
-      - name: Zip coverage and upload to Quality Dashboard
-        if: always()
-        env:
-          QUALITY_DASHBOARD_URL: ${{ secrets.QUALITY_DASHBOARD_URL }}
-          QUALITY_DASHBOARD_TOKEN: ${{ secrets.QUALITY_DASHBOARD_TOKEN }}
-        run: |
-          APP_NAME="${{ matrix.app }}"
-          PACKAGE_NAME=$(node -p "require('./package.json').name")
-          REPORT_KEY="$(echo "$APP_NAME" | sed 's/[^a-zA-Z0-9._:\-\/]/_/g')_coverage"
-
-          if [ -d coverage ]; then
-            if [ -z "$QUALITY_DASHBOARD_URL" ] || [ -z "$QUALITY_DASHBOARD_TOKEN" ]; then
-              echo "Quality Dashboard URL or token not set, skipping upload"
-              exit 0
-            fi
-            # Zip coverage contents at root level so the jest processor
-            # finds coverage-final.json / clover.xml directly
-            (cd coverage && zip -r "${{ runner.temp }}/coverage.zip" .)
-
-            META=$(jq -n \
-              --arg key "$REPORT_KEY" \
-              --arg pkg "$PACKAGE_NAME" \
-              '{
-                key: $key,
-                displayName: "Coverage: \($pkg)",
-                processor: "jest"
-              }')
-
-            echo "Uploading coverage: $REPORT_KEY"
-            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
-              -X POST "$QUALITY_DASHBOARD_URL/api/reports/" \
-              -H "x-upload-token: $QUALITY_DASHBOARD_TOKEN" \
-              -F "meta=$META" \
-              -F "file=@${{ runner.temp }}/coverage.zip" \
-              --max-time 30)
-
-            if [ "$HTTP_CODE" = "201" ]; then
-              echo "\u2713 Coverage uploaded ($HTTP_CODE)"
-            else
-              echo "\u26a0 Upload returned HTTP $HTTP_CODE"
-            fi
-          else
-            echo "No coverage/ directory found, skipping upload"
-          fi
+# Immutable build strategy: the image validated on the pull request is promoted
+# as-is, so merging runs no build, lint or test.
+#
+# `contents: read` only. Callers run with the default read-only token, whose
+# ceiling is `contents: read, pull-requests: none`, so requesting anything more
+# here makes the caller fail to start with "Invalid workflow file". The PR is
+# therefore resolved without needing pull-request scopes.
+permissions:
+  contents: read
 
-  docker-build:
+jobs:
+  promote-image:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -122,20 +56,142 @@ jobs:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
 
-      - name: Build and Push Docker Image
+      - name: Resolve the image validated by the merged PR
+        id: resolve
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
         run: |
           set -e
-          SERVICE_NAME=$(cat package.json | jq -r '.name')
-          SERVICE_VERSION=$(cat package.json | jq -r '.version')
-          SERVICE_VERSION_MAJOR=$(echo "${SERVICE_VERSION}" | cut -f1 -d".")
-          SERVICE_VERSION_MINOR=$(echo "${SERVICE_VERSION}" | cut -f1-2 -d".")
-          echo "Building ${SERVICE_NAME}:${SERVICE_VERSION}"
+          SERVICE_NAME=$(jq -r '.name' package.json)
+          SERVICE_VERSION=$(jq -r '.version' package.json)
+          IMAGE="${DOCKER_HUB_USERNAME}/${SERVICE_NAME}"
+
+          PR_NUMBER=""
+          PR_SOURCE="none"
+
+          # Preferred: ask the API which PR introduced this commit. This needs
+          # `pull-requests: read`, which callers on the default token are not
+          # granted, so a failure here is expected rather than exceptional.
+          PR_NUMBER=$(curl -sfL \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/commits/${GITHUB_SHA}/pulls" \
+            | jq -r '.[0].number // empty' || true)
+          if [ -n "${PR_NUMBER}" ]; then
+            PR_SOURCE="api"
+          fi
+
+          # Fallback: parse the commit title, where GitHub writes the PR number
+          # for squash ("<title> (#123)") and merge ("Merge pull request #123")
+          # commits. Only the title is read, so a "fixes #99" reference in the
+          # commit body cannot select the wrong pull request.
+          if [ -z "${PR_NUMBER}" ]; then
+            TITLE=$(git log -1 --pretty=%s)
+            PR_NUMBER=$(printf '%s' "${TITLE}" | grep -oE '\(#[0-9]+\)' | tail -1 | tr -d '(#)' || true)
+            if [ -z "${PR_NUMBER}" ]; then
+              PR_NUMBER=$(printf '%s' "${TITLE}" | grep -oE 'Merge pull request #[0-9]+' | grep -oE '[0-9]+' | head -1 || true)
+            fi
+            if [ -n "${PR_NUMBER}" ]; then
+              PR_SOURCE="commit-title"
+            fi
+          fi
+
+          SOURCE_IMAGE=""
+          if [ -z "${PR_NUMBER}" ]; then
+            echo "::warning::No pull request found for ${GITHUB_SHA}, falling back to a build."
+          else
+            CANDIDATE="${IMAGE}:beta-pr-${PR_NUMBER}"
+            if docker buildx imagetools inspect "${CANDIDATE}" > /dev/null 2>&1; then
+              SOURCE_IMAGE="${CANDIDATE}"
+            else
+              echo "::warning::${CANDIDATE} not found in the registry, falling back to a build."
+            fi
+          fi
+
+          if [ -n "${SOURCE_IMAGE}" ]; then
+            STRATEGY="retag"
+          else
+            STRATEGY="build"
+          fi
+
+          {
+            echo "image=${IMAGE}"
+            echo "service_name=${SERVICE_NAME}"
+            echo "service_version=${SERVICE_VERSION}"
+            echo "pr_number=${PR_NUMBER}"
+            echo "pr_source=${PR_SOURCE}"
+            echo "source_image=${SOURCE_IMAGE}"
+            echo "strategy=${STRATEGY}"
+          } >> "${GITHUB_OUTPUT}"
+
+          echo "Service:  ${SERVICE_NAME} ${SERVICE_VERSION}"
+          echo "PR:       ${PR_NUMBER:-none} (resolved via ${PR_SOURCE})"
+          echo "Source:   ${SOURCE_IMAGE:-none}"
+          echo "Strategy: ${STRATEGY}"
+
+      - name: Promote the PR image to the release tags
+        if: steps.resolve.outputs.strategy == 'retag'
+        env:
+          RELEASE_IMAGE: ${{ steps.resolve.outputs.image }}
+          RELEASE_VERSION: ${{ steps.resolve.outputs.service_version }}
+          SOURCE_IMAGE: ${{ steps.resolve.outputs.source_image }}
+          MERGED_PR_NUMBER: ${{ steps.resolve.outputs.pr_number }}
+        run: |
+          set -e
+          MAJOR=$(echo "${RELEASE_VERSION}" | cut -f1 -d".")
+          MINOR=$(echo "${RELEASE_VERSION}" | cut -f1-2 -d".")
+
+          SOURCE_DIGEST=$(docker buildx imagetools inspect "${SOURCE_IMAGE}" --format '{{.Manifest.Digest}}')
+
+          echo "Promoting ${SOURCE_IMAGE} (PR #${MERGED_PR_NUMBER})"
+          echo "  digest ${SOURCE_DIGEST}"
+          echo "  -> ${RELEASE_IMAGE}:${RELEASE_VERSION}"
+          echo "  -> ${RELEASE_IMAGE}:${MAJOR}"
+          echo "  -> ${RELEASE_IMAGE}:${MINOR}"
+          echo "  -> ${RELEASE_IMAGE}:latest"
+
+          # --prefer-index=false forces a carbon copy of the source manifest, so
+          # the released image keeps the exact digest validated on the pull
+          # request. Without it, a single-platform source would be rewrapped into
+          # a new image index and the digest would change.
+          docker buildx imagetools create \
+            --prefer-index=false \
+            -t "${RELEASE_IMAGE}:${RELEASE_VERSION}" \
+            -t "${RELEASE_IMAGE}:${MAJOR}" \
+            -t "${RELEASE_IMAGE}:${MINOR}" \
+            -t "${RELEASE_IMAGE}:latest" \
+            "${SOURCE_IMAGE}"
+
+          # Fail loudly rather than publish an artifact that differs from the one
+          # tested on the pull request.
+          for TAG in "${RELEASE_VERSION}" "${MAJOR}" "${MINOR}" "latest"; do
+            PROMOTED_DIGEST=$(docker buildx imagetools inspect "${RELEASE_IMAGE}:${TAG}" --format '{{.Manifest.Digest}}')
+            if [ "${PROMOTED_DIGEST}" != "${SOURCE_DIGEST}" ]; then
+              echo "::error::${RELEASE_IMAGE}:${TAG} has digest ${PROMOTED_DIGEST}, expected ${SOURCE_DIGEST}"
+              exit 1
+            fi
+            echo "  verified ${RELEASE_IMAGE}:${TAG} -> ${PROMOTED_DIGEST}"
+          done
+
+      - name: Build and Push Docker Image (fallback)
+        if: steps.resolve.outputs.strategy == 'build'
+        env:
+          RELEASE_IMAGE: ${{ steps.resolve.outputs.image }}
+          RELEASE_VERSION: ${{ steps.resolve.outputs.service_version }}
+          DOCKER_PLATFORMS: ${{ inputs.docker_platforms }}
+        run: |
+          set -e
+          MAJOR=$(echo "${RELEASE_VERSION}" | cut -f1 -d".")
+          MINOR=$(echo "${RELEASE_VERSION}" | cut -f1-2 -d".")
+
+          echo "Building ${RELEASE_IMAGE}:${RELEASE_VERSION} from ${GITHUB_SHA}"
           docker buildx build \
-            --platform ${{ inputs.docker_platforms }} \
+            --platform "${DOCKER_PLATFORMS}" \
             --push \
             -f Dockerfile \
-            -t ${{ secrets.DOCKER_HUB_USERNAME }}/${SERVICE_NAME}:latest \
-            -t ${{ secrets.DOCKER_HUB_USERNAME }}/${SERVICE_NAME}:${SERVICE_VERSION} \
-            -t ${{ secrets.DOCKER_HUB_USERNAME }}/${SERVICE_NAME}:${SERVICE_VERSION_MAJOR} \
-            -t ${{ secrets.DOCKER_HUB_USERNAME }}/${SERVICE_NAME}:${SERVICE_VERSION_MINOR} \
+            -t "${RELEASE_IMAGE}:latest" \
+            -t "${RELEASE_IMAGE}:${RELEASE_VERSION}" \
+            -t "${RELEASE_IMAGE}:${MAJOR}" \
+            -t "${RELEASE_IMAGE}:${MINOR}" \
             .

package/.github/workflows/reusable-pr-verify.yml

@@ -123,13 +123,28 @@ jobs:
           password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
 
       - name: Build and Push Docker Image
+        env:
+          DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
+          DOCKER_PLATFORMS: ${{ inputs.docker_platforms }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
           set -e
-          SERVICE_NAME=$(cat package.json | jq -r '.name')
-          echo "Building ${SERVICE_NAME}:beta"
+          SERVICE_NAME=$(jq -r '.name' package.json)
+          IMAGE="${DOCKER_HUB_USERNAME}/${SERVICE_NAME}"
+
+          # `beta-pr-<number>` is the immutable per-PR reference: it identifies
+          # exactly the artifact validated by this pull request, and the merge
+          # build promotes it as-is to the semantic version tags.
+          PR_TAG="${PR_NUMBER}"
+          if [ -z "${PR_TAG}" ]; then
+            PR_TAG="manual-${GITHUB_SHA::7}"
+          fi
+
+          echo "Building ${IMAGE}:beta-pr-${PR_TAG} and ${IMAGE}:beta"
           docker buildx build \
-            --platform ${{ inputs.docker_platforms }} \
+            --platform "${DOCKER_PLATFORMS}" \
             --push \
             -f Dockerfile \
-            -t ${{ secrets.DOCKER_HUB_USERNAME }}/${SERVICE_NAME}:beta \
+            -t "${IMAGE}:beta-pr-${PR_TAG}" \
+            -t "${IMAGE}:beta" \
             .

package/AGENTS.md

@@ -38,8 +38,8 @@ src/
   reusable-npm-merge.yml    # Lint + test + build + publish release to npm
   reusable-npm-pr.yml       # Lint + test + build + publish beta tag + comment PR
   reusable-npm-upgrade.yml  # npm-check-updates + auto PR
-  reusable-pr-verify.yml    # Matrix Node.js + multi-platform Docker build for PRs
-  reusable-merge-build.yml  # Matrix Node.js + Docker build with version tags on merge
+  reusable-pr-verify.yml    # Matrix Node.js + multi-platform Docker build -> beta-pr-<PR> and beta
+  reusable-merge-build.yml  # Promotes the PR image to the version tags on merge (no build/lint/test)
 ```
 
 ## Key Conventions
@@ -53,6 +53,8 @@ src/
 - **ModuleLogger pattern**: `StandardLogger` only exposes `createModuleLogger(name)`. DB modules call `logger.createModuleLogger("ModuleName")` internally. Never call `.info()` or `.error()` directly on a `StandardLogger`.
 - **SQLite-first SQL**: Write SQL with `?` placeholders. The `DbUtils` facade and `DbUtilsNoTelemetry` module auto-convert to `$1, $2, ...` for Postgres via `convertToPostgresPlaceholders()`.
 - **Migration convention**: SQL files named `init-NNNN.sql`. `init-0000.sql` must create the `metadata` table. Subsequent files are applied in lexicographic order; applied versions are tracked in `metadata` for idempotency.
+- **Immutable Docker builds**: images are built once on the pull request (`reusable-pr-verify.yml` pushes `beta-pr-<PR number>` and `beta`) and promoted unchanged on merge (`reusable-merge-build.yml` writes `<version>`, `<major>`, `<minor>` and `latest`). The merge workflow runs no build, lint or test: it resolves the merged PR, carbon-copies the manifest with `docker buildx imagetools create --prefer-index=false`, then reads back each published digest and fails on a mismatch. It falls back to a full build only when no `beta-pr-<PR number>` image can be promoted. Image name and version come from the root `package.json`, and PR branches must be up to date with the default branch before merging.
+- **Reusable workflow permissions ceiling**: `reusable-merge-build.yml` may request only `contents: read`. A called workflow cannot exceed its caller's permissions, and callers use the default read-only token whose ceiling is `contents: read, pull-requests: none`. Adding `pull-requests: read` does not fail here — it fails in every consuming repo at startup with `Invalid workflow file ... requesting 'pull-requests: read', but is only allowed 'pull-requests: none'`. `GET /repos/{owner}/{repo}/commits/{sha}/pulls` works with `contents: read`, so no extra scope is needed.
 
 ## Build and Verification
 

package/README.md

@@ -484,8 +484,8 @@ The `.github/workflows/` directory contains **reusable workflows** that other re
 | **NPM Merge**   | `reusable-npm-merge.yml`   | `workflow_call` | Lint, test, build, and publish a release to npm on merge to main. Uploads coverage to Quality Dashboard. Only publishes if the version doesn't already exist. |
 | **NPM PR**      | `reusable-npm-pr.yml`      | `workflow_call` | Lint, test, and build on PR. Publishes a **beta** version tagged `beta` and comments the PR with install instructions.                                        |
 | **NPM Upgrade** | `reusable-npm-upgrade.yml` | `workflow_call` | Runs `npm-check-updates -u`, bumps the patch version, and opens a PR. Supports monorepo sub-folders via `npm_services` input.                                 |
-| **PR Verify**   | `reusable-pr-verify.yml`   | `workflow_call` | Matrix build/lint/test for multiple Node.js apps plus multi-platform Docker build. For monorepos with Docker images.                                          |
-| **Merge Build** | `reusable-merge-build.yml` | `workflow_call` | Same as PR Verify but on merge. Tags Docker images with `latest`, version, major, and minor tags.                                                             |
+| **PR Verify**   | `reusable-pr-verify.yml`   | `workflow_call` | Matrix build/lint/test for multiple Node.js apps, plus a multi-platform Docker build pushed as `beta-pr-<PR number>` and `beta`. For monorepos with Docker images. |
+| **Merge Build** | `reusable-merge-build.yml` | `workflow_call` | Promotes the image validated by the merged PR to the `latest`, version, major and minor tags. Runs no build, lint or test.                                      |
 
 ### Inputs and Secrets
 
@@ -517,6 +517,8 @@ The `.github/workflows/` directory contains **reusable workflows** that other re
 | `node_app_directories` | No       | `""`                         | JSON array of Node.js app directories |
 | `node_version`         | No       | `"22"`                       | Node.js version                       |
 
+`reusable-merge-build` declares the same inputs so existing callers keep working, but it only reads `docker_platforms`, and only on the build fallback path. `node_app_directories` and `node_version` are ignored there because merging runs no Node.js job.
+
 | Secret                    | Required | Description                    |
 | ------------------------- | -------- | ------------------------------ |
 | `DOCKER_HUB_USERNAME`     | Yes      | Docker Hub username            |
@@ -524,6 +526,44 @@ The `.github/workflows/` directory contains **reusable workflows** that other re
 | `QUALITY_DASHBOARD_URL`   | No       | Quality Dashboard URL          |
 | `QUALITY_DASHBOARD_TOKEN` | No       | Quality Dashboard upload token |
 
+`reusable-merge-build` also still declares the Quality Dashboard secrets for backward compatibility, but no longer uploads coverage: each report is produced once, on the pull request.
+
+### Immutable Docker Build Strategy
+
+Docker images are built **once**, on the pull request, and **promoted** on merge. The artifact you test is bit-for-bit the artifact you release.
+
+| Stage            | Workflow               | Registry tags written                                                                                       |
+| ---------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Pull request     | `reusable-pr-verify`   | `beta-pr-<PR number>` (identifies this PR's artifact) and `beta` (moving pointer to the latest PR build)     |
+| Merge to default | `reusable-merge-build` | `<version>`, `<major>`, `<minor>` and `latest`, copied from `beta-pr-<PR number>`                            |
+
+On merge the workflow:
+
+1. Resolves the pull request behind the commit pushed to the default branch through `GET /repos/{owner}/{repo}/commits/{sha}/pulls`, falling back to the PR number in the commit **title** (`<title> (#123)` for squash and rebase, `Merge pull request #123` for merge commits). Only the title is parsed, so a `fixes #99` reference in the commit body cannot select the wrong pull request.
+2. Carbon-copies the manifest with `docker buildx imagetools create --prefer-index=false`, which preserves the exact digest and the full multi-platform image index.
+3. Reads back the digest of every tag it published and fails if one differs from the source.
+
+The resolve step logs how it reached its answer, which is the first thing to check when a merge falls back to a build:
+
+```text
+Service:  planner-llm-agent 0.2.0
+PR:       2 (resolved via api)
+Source:   <namespace>/planner-llm-agent:beta-pr-2
+Strategy: retag
+```
+
+`Strategy` is `retag` when the PR image was found and `build` when it was not.
+
+No `npm ci`, build, lint or test runs on merge, and no Docker build happens unless promotion is impossible. The build fallback keeps releases working when a commit reaches the default branch with no matching `beta-pr-<PR number>` image, such as a direct push, a rebase merge (which leaves no PR number in the commit title), or a PR whose image was deleted from the registry.
+
+> **Callers need no `permissions:` block.** `reusable-merge-build` requests only `contents: read`. A reusable workflow cannot ask for more than its caller is allowed, and the default read-only token ceiling is `contents: read, pull-requests: none` — requesting `pull-requests: read` makes the caller fail to start with `Invalid workflow file … The workflow is requesting 'pull-requests: read', but is only allowed 'pull-requests: none'`. The API lookup above works with `contents: read` alone.
+
+The image name and version come from the root `package.json`, so bump the minor version in the pull request that carries the change.
+
+> **Keep PR branches up to date with the default branch before merging.** The promoted image is the one built from the PR head, so if the default branch moved in the meantime the released artifact will not contain those commits.
+
+Validated end to end on `planner-llm-agent` 0.2.0: the pull request pushed `beta-pr-2` and `beta`, the merge promoted that image in **40 seconds** with no build, and `beta-pr-2`, `beta`, `0.2.0`, `0.2`, `0` and `latest` all resolve to the single digest `sha256:710fed19…` with identical per-architecture digests.
+
 ### Adopting in Your Project
 
 Create a caller workflow in `.github/workflows/main-build.yml`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.6.0-beta.15.02b378d",
+  "version": "1.7.0-beta.16.179c4ff",
   "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, auth/users, notifications, LLM, system helpers)",
   "keywords": [
     "Open Telemetry",