cpflow 6.0.0.rc.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73c78e337b3728ba8273db59f8f7d9540e855e986ba7aed509c3091a7cf806dd
-  data.tar.gz: d399af718dd0ab5a103d13b2eb7bc3515d2839077280254c29563fa88f14559d
+  metadata.gz: 2abf58d5c1099a9f57164ebe03843c014180098e23551d73822419b05191070a
+  data.tar.gz: ab7adb1a83dbea1215c5686748e1438006a3a58ce419d1797a53172a670ce86e
 SHA512:
-  metadata.gz: ad64de2a50dac54f6c9ee541ec8a2e80f13a36b81cedc2c58924c881ed80df8ff5f6c231255cae7328fbeeda80992e98fbab613f406f149478e7be2711a5a958
-  data.tar.gz: 927713a8b5e829ec6c89aef86ba9020d686bf6b1647473efbb356f31f9ca590185b8c582c061afd555ad32efa6f6caf38c834fba03cf56a52b2a7970f239f2db
+  metadata.gz: 4fcb5b12cc9b4ce2edec7afc583bdd37a62812a40e5ea478e1efc09a29e82d3d0bfe47386001b3978a11bcc3deb342044596c54d52eecc605e5a04077fa322be
+  data.tar.gz: e5f33d39830fffc5fcb66e9f22aeb5d519c1ed18b51ae1ec77fe7a65c9e26b42426bac48aeaa5e62bff5c218c6cc2f5e9f131fdfd211cd2343a9c0671afa7880

data/.agents/agent-workflow.yml

@@ -1,39 +1,17 @@
-# Non-command agent-workflow configuration for portable shared skills.
-# This file is the canonical source for the non-command policy values below.
-# AGENTS.md directs portable skills here; it does not duplicate or override them.
-# Commands live as scripts in .agents/bin/ (see .agents/bin/README.md).
+---
+version: 1
 base_branch: main
-merge_submission:
-  mode: direct
-changelog: "CHANGELOG.md — Keep-a-Changelog; user-visible changes only"
-follow_up_prefix: "Follow-up:"
-review_gate: "AI reviewers are advisory unless they confirm a blocker; merge gate is the full `gh pr checks` list green (not --required) + all threads resolved + mergeable clean"
-approval_exempt: "at batch closeout, auto-merge ready low-risk PRs that pass the merge gate; keep high-risk (CI/workflow, build-config, dependency or runtime bumps, broad refactors, release) maintainer-gated"
-coordination_backend: "private shakacode/agent-coordination (claims/heartbeats namespaced by full repo name)"
-benchmark_labels: n/a
-merge_ledger: n/a
-ci_parity_environment: "n/a — reproduce CI-only failures from the matching job in .github/workflows/**"
-release_qa_runbook: ".agents/workflows/ai-rollout-e2e-test.md — use after publishing a cpflow gem that changes GitHub Actions, AI rollout prompts, readiness checks, generator output, or React on Rails deployment behavior"
-hosted_ci_trigger: "n/a — CI runs on every PR"
-ci_change_detector: n/a
-
-# Consumed by the portable untrusted-contributor-intake skill. These values must
-# be read from the trusted base ref, never from contributor-controlled PR content.
-untrusted_contributor_intake:
-  trusted_github_host: github.com
-  trusted_github_scheme: https
-  trusted_github_repo: shakacode/control-plane-flow
-repo_prefix: CPF
-
-# External actions already used by this repository and reviewed for the closed
-# allowlist enforced by the GitHub Actions security scanner. Every use still
-# requires an immutable commit SHA and a same-line release-version comment.
-trusted_actions:
-  - actions/checkout
-  - actions/create-github-app-token
-  - actions/github-script
-  - actions/upload-artifact
-  - anthropics/claude-code-action
-  - docker/setup-buildx-action
-  - peter-evans/repository-dispatch
-  - ruby/setup-ruby
+review:
+  required: none
+  # Local reviewer preference; independent from hosted review workflows.
+  local_review_agents:
+    - provider: anthropic
+      model_family: claude
+    - provider: openai
+      model_family: codex
+merge:
+  preference: ask
+branches:
+  name: "{login}-{host}/{issue}-{description}"
+wip:
+  include_locations: false

data/.agents/bin/README.md

@@ -1,9 +1,8 @@
 # Agent Workflow Scripts
 
-Standard entry points that portable agent-workflow skills call, so a skill can
-run `.agents/bin/<name>` in any repo without knowing this repo's specific
-commands. Each script is a thin, repo-owned wrapper. A script that is **absent**
-means that capability is n/a here.
+Thin, repo-owned command wrappers. Shaka's typed contract uses `setup`,
+`validate`, and `test`; the remaining scripts are additional repository helpers.
+A script that is **absent** means that capability is n/a here.
 
 | Script | Purpose | This repo runs |
 | --- | --- | --- |
@@ -25,7 +24,7 @@ update that array and its inventory regression test; use a `.sh` or `.bash`
 suffix for automatic inclusion. Declared paths must remain tracked and readable.
 Unlisted extensionless files and non-shell files are outside this check.
 
-Canonical non-command policy, including the release-QA runbook reference, lives
-in [`../agent-workflow.yml`](../agent-workflow.yml). [`../../AGENTS.md`](../../AGENTS.md)
-is the thin discovery pointer for portable shared skills and does not duplicate
-or override that policy.
+Canonical typed Shaka policy lives in
+[`../agent-workflow.yml`](../agent-workflow.yml). The GitHub Actions dependency allowlist lives in
+[`../trusted-actions.yml`](../trusted-actions.yml). Additional agent-binding repository policy,
+including the release-QA runbook reference, lives in [`../../AGENTS.md`](../../AGENTS.md).

data/.agents/legacy-workflow-policy.yml

@@ -0,0 +1,11 @@
+---
+# Trusted policy retained for tools that have not migrated to Shaka's typed
+# repository contract. This file is not part of the Shaka seam. Read every
+# value from a trusted base ref established before reading candidate content.
+# Missing, unreadable, or invalid values must fail closed.
+untrusted_contributor_intake:
+  trusted_github_host: github.com
+  trusted_github_scheme: https
+  trusted_github_repo: shakacode/control-plane-flow
+repo_prefix: CPF
+coordination_backend: "private shakacode/agent-coordination (claims/heartbeats namespaced by full repo name)"

data/.agents/shaka.md

@@ -0,0 +1,20 @@
+# Shaka configuration
+
+Shaka package / skill release: `0.1.0.pre.1`.
+
+## Migration reference
+
+This repo pins its Shaka reader source to the revision containing the [migration
+procedure at `8431a718cfd91e9ce7cb4276baae076848e05d13`](https://github.com/shakacode/shaka/blob/8431a718cfd91e9ce7cb4276baae076848e05d13/skills/shaka/references/migration.md).
+At that Shaka revision, `skills/shaka/lib/shaka/version.rb` defines the package
+release and `docs/settings.md` documents the typed seam. The migration procedure
+describes key changes and the two-step validation used for first adoption.
+
+## Check configuration edits
+
+Run from the repository root:
+
+`shaka seam check --root . --local`
+
+Checks the current checkout's YAML and fixed-script paths and executable bits. It
+does not execute the wrappers and grants no trusted policy authority.

data/.agents/trusted-actions.yml

@@ -0,0 +1,12 @@
+---
+# External GitHub Actions repositories reviewed for use by this repository.
+# Keep this list synchronized with the workflow dependency policy spec.
+trusted_actions:
+  - actions/checkout
+  - actions/create-github-app-token
+  - actions/github-script
+  - actions/upload-artifact
+  - anthropics/claude-code-action
+  - docker/setup-buildx-action
+  - peter-evans/repository-dispatch
+  - ruby/setup-ruby

data/.coderabbit.yaml

@@ -1,5 +1,6 @@
 reviews:
   profile: chill
+  high_level_summary: false
   review_status: false
   review_progress: false
   commit_status: false

data/.github/actions/cpflow-build-docker-image/action.yml

@@ -17,6 +17,9 @@ inputs:
   docker_build_extra_args:
     description: Optional newline-delimited extra docker build tokens. Use key=value forms like --build-arg=FOO=bar.
     required: false
+  docker_build_secrets:
+    description: Optional newline-delimited id=value secrets, passed through BuildKit secret mounts.
+    required: false
   docker_build_ssh_key:
     description: Optional private SSH key used for Docker builds that fetch private dependencies with RUN --mount=type=ssh
     required: false
@@ -31,17 +34,56 @@ inputs:
 runs:
   using: composite
   steps:
+    - name: Prepare Docker build secrets
+      id: build-secrets
+      if: ${{ inputs.docker_build_secrets != '' }}
+      shell: bash
+      env:
+        DOCKER_BUILD_SECRETS: ${{ inputs.docker_build_secrets }}
+      run: |
+        set -euo pipefail
+        umask 077
+        secret_directory="$(mktemp -d "${RUNNER_TEMP}/cpflow-build-secrets.XXXXXX")"
+        secrets_ready=false
+        trap 'if [[ "${secrets_ready}" != "true" ]]; then rm -rf "${secret_directory}"; fi' EXIT
+        while IFS= read -r entry || [[ -n "${entry}" ]]; do
+          entry="${entry%$'\r'}"
+          [[ -n "${entry}" ]] || continue
+          if [[ "${entry}" != *=* ]]; then
+            echo "Docker build secrets must use id=value entries." >&2
+            exit 1
+          fi
+          secret_id="${entry%%=*}"
+          secret_value="${entry#*=}"
+          if [[ ! "${secret_id}" =~ ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ ]] || [[ -z "${secret_value}" ]]; then
+            echo "Docker build secrets require a valid id and a nonempty value." >&2
+            exit 1
+          fi
+          if [[ -e "${secret_directory}/${secret_id}" ]]; then
+            echo "Duplicate Docker build secret id." >&2
+            exit 1
+          fi
+          # GitHub masks the stored id=value entry; register the extracted value too.
+          masked_value="${secret_value//%/%25}"
+          masked_value="${masked_value//$'\r'/%0D}"
+          masked_value="${masked_value//$'\n'/%0A}"
+          printf '::add-mask::%s\n' "${masked_value}"
+          printf '%s' "${secret_value}" > "${secret_directory}/${secret_id}"
+        done <<< "${DOCKER_BUILD_SECRETS}"
+        echo "directory=${secret_directory}" >> "${GITHUB_OUTPUT}"
+        secrets_ready=true
+
     # Keep SSH key handling in a dedicated step so DOCKER_BUILD_SSH_KEY is never present
     # in the main build step's environment. ACTIONS_STEP_DEBUG=true dumps env before any
     # command runs, so keeping the key out of env there avoids even admin-triggered exposure.
     - name: Prepare SSH agent for Docker build
+      id: prepare-build-ssh
       if: ${{ inputs.docker_build_ssh_key != '' }}
       shell: bash
       env:
-        # Pass the key via env so the file write is a single printf call rather than a
-        # heredoc with a fixed terminator (a heredoc would silently truncate the key if
-        # any line of the key value happened to match the terminator). Scope is still
-        # this step only — the build step below does not receive DOCKER_BUILD_SSH_KEY.
+        # Pass the key via env so ssh-add can read it from stdin without persisting it to
+        # disk. Scope is this step only — the build step below receives the agent socket,
+        # not DOCKER_BUILD_SSH_KEY.
         DOCKER_BUILD_SSH_KEY: ${{ inputs.docker_build_ssh_key }}
         DOCKER_BUILD_SSH_KNOWN_HOSTS: ${{ inputs.docker_build_ssh_known_hosts }}
       run: |
@@ -51,6 +93,49 @@ runs:
         mkdir -p ~/.ssh
         chmod 700 ~/.ssh
 
+        known_hosts_backup="${HOME}/.ssh/cpflow_known_hosts_backup"
+        if [[ -e "${known_hosts_backup}" ]]; then
+          echo "Refusing to replace SSH known_hosts: a prior cpflow backup exists at ${known_hosts_backup}." >&2
+          echo "If no build is currently running on this runner, restore or remove that backup, then retry." >&2
+          exit 1
+        fi
+
+        known_hosts_backup_ready=false
+        known_hosts_replaced=false
+        ssh_agent_started=false
+        restore_known_hosts_on_prep_failure() {
+          status=$?
+          if [[ "${status}" -ne 0 ]]; then
+            if [[ "${ssh_agent_started}" == "true" ]]; then
+              ssh-agent -k >/dev/null || true
+            fi
+            if [[ "${known_hosts_backup_ready}" == "true" ]]; then
+              mv -f -- "${known_hosts_backup}" "${HOME}/.ssh/known_hosts"
+            else
+              rm -f "${known_hosts_backup}"
+              if [[ "${known_hosts_replaced}" == "true" ]]; then
+                rm -f "${HOME}/.ssh/known_hosts"
+              fi
+            fi
+          fi
+          exit "${status}"
+        }
+        trap restore_known_hosts_on_prep_failure EXIT
+
+        if [[ -L "${HOME}/.ssh/known_hosts" ]]; then
+          echo "Refusing to replace symlinked SSH known_hosts." >&2
+          exit 1
+        fi
+        if [[ -e "${HOME}/.ssh/known_hosts" ]]; then
+          if [[ ! -f "${HOME}/.ssh/known_hosts" ]]; then
+            echo "Refusing to replace non-file SSH known_hosts." >&2
+            exit 1
+          fi
+          cp -p -- "${HOME}/.ssh/known_hosts" "${known_hosts_backup}"
+          known_hosts_backup_ready=true
+        fi
+
+        known_hosts_replaced=true
         if [[ -n "${DOCKER_BUILD_SSH_KNOWN_HOSTS}" ]]; then
           printf '%s\n' "${DOCKER_BUILD_SSH_KNOWN_HOSTS}" > ~/.ssh/known_hosts
         else
@@ -62,8 +147,15 @@ runs:
         fi
         chmod 600 ~/.ssh/known_hosts
 
-        printf '%s\n' "${DOCKER_BUILD_SSH_KEY}" > ~/.ssh/cpflow_build_key
-        chmod 600 ~/.ssh/cpflow_build_key
+        eval "$(ssh-agent -s)"
+        ssh_agent_started=true
+        printf '%s\n' "${DOCKER_BUILD_SSH_KEY}" | ssh-add -
+        {
+          echo "prepared=true"
+          echo "known_hosts_had_original=${known_hosts_backup_ready}"
+          echo "ssh_auth_sock=${SSH_AUTH_SOCK}"
+          echo "ssh_agent_pid=${SSH_AGENT_PID}"
+        } >> "${GITHUB_OUTPUT}"
 
     - name: Build Docker image
       shell: bash
@@ -71,27 +163,34 @@ runs:
         APP_NAME: ${{ inputs.app_name }}
         COMMIT_SHA: ${{ inputs.commit }}
         CONTROL_PLANE_ORG: ${{ inputs.org }}
+        DOCKER_BUILD_SECRET_DIRECTORY: ${{ steps.build-secrets.outputs.directory }}
         DOCKER_BUILD_EXTRA_ARGS: ${{ inputs.docker_build_extra_args }}
         PR_NUMBER: ${{ inputs.pr_number }}
+        CPFLOW_BUILD_SSH_PREPPED: ${{ steps.prepare-build-ssh.outputs.prepared }}
+        CPFLOW_KNOWN_HOSTS_HAD_ORIGINAL: ${{ steps.prepare-build-ssh.outputs.known_hosts_had_original }}
+        SSH_AUTH_SOCK: ${{ steps.prepare-build-ssh.outputs.ssh_auth_sock }}
+        SSH_AGENT_PID: ${{ steps.prepare-build-ssh.outputs.ssh_agent_pid }}
         WORKING_DIRECTORY: ${{ inputs.working_directory }}
       run: |
         set -euo pipefail
 
         PR_INFO=""
         docker_build_args=()
-        ssh_agent_started=false
-        build_ssh_prepped=false
+        build_ssh_prepped="${CPFLOW_BUILD_SSH_PREPPED:-false}"
 
         cleanup_build_ssh() {
-          if [[ "${ssh_agent_started}" == "true" ]]; then
-            ssh-agent -k >/dev/null || true
+          if [[ -n "${DOCKER_BUILD_SECRET_DIRECTORY:-}" ]]; then
+            rm -rf -- "${DOCKER_BUILD_SECRET_DIRECTORY}"
           fi
-          rm -f "${HOME}/.ssh/cpflow_build_key"
-          # Only remove known_hosts if this action's prep step wrote it. On self-hosted
-          # or reused runners we must not touch a user-managed file we did not create,
-          # so the flag is set inside the same prep-detection branch below.
           if [[ "${build_ssh_prepped}" == "true" ]]; then
-            rm -f "${HOME}/.ssh/known_hosts"
+            ssh-agent -k >/dev/null || true
+            # Restore a pre-existing known_hosts file on reused runners. When there was
+            # no original file, remove only the file created by this action.
+            if [[ -f "${HOME}/.ssh/cpflow_known_hosts_backup" ]]; then
+              mv -f -- "${HOME}/.ssh/cpflow_known_hosts_backup" "${HOME}/.ssh/known_hosts"
+            else
+              rm -f "${HOME}/.ssh/known_hosts"
+            fi
           fi
         }
         trap cleanup_build_ssh EXIT
@@ -116,16 +215,48 @@ runs:
           done <<< "${DOCKER_BUILD_EXTRA_ARGS}"
         fi
 
-        if [[ -f "${HOME}/.ssh/cpflow_build_key" ]]; then
-          # Mark prep-step ownership so cleanup_build_ssh only removes known_hosts
-          # when this action wrote it (see trap above).
-          build_ssh_prepped=true
-          eval "$(ssh-agent -s)"
-          ssh_agent_started=true
-          ssh-add "${HOME}/.ssh/cpflow_build_key"
+        if [[ "${build_ssh_prepped}" == "true" ]]; then
           docker_build_args+=("--ssh=default")
         fi
 
+        if [[ -n "${DOCKER_BUILD_SECRET_DIRECTORY:-}" ]]; then
+          for secret_path in "${DOCKER_BUILD_SECRET_DIRECTORY}"/*; do
+            [[ -f "${secret_path}" ]] || continue
+            docker_build_args+=("--secret=id=${secret_path##*/},src=${secret_path}")
+          done
+        fi
+
         echo "🏗️ Building Docker image${PR_INFO} (commit ${COMMIT_SHA})..."
         cpflow build-image -a "${APP_NAME}" --commit="${COMMIT_SHA}" --org="${CONTROL_PLANE_ORG}" "${docker_build_args[@]}"
         echo "✅ Docker image build successful${PR_INFO} (commit ${COMMIT_SHA})"
+
+    - name: Clean up SSH build state
+      if: ${{ always() && inputs.docker_build_ssh_key != '' }}
+      shell: bash
+      env:
+        CPFLOW_BUILD_SSH_PREPPED: ${{ steps.prepare-build-ssh.outputs.prepared }}
+        CPFLOW_KNOWN_HOSTS_HAD_ORIGINAL: ${{ steps.prepare-build-ssh.outputs.known_hosts_had_original }}
+        SSH_AUTH_SOCK: ${{ steps.prepare-build-ssh.outputs.ssh_auth_sock }}
+        SSH_AGENT_PID: ${{ steps.prepare-build-ssh.outputs.ssh_agent_pid }}
+      run: |
+        set +e
+
+        if [[ "${CPFLOW_BUILD_SSH_PREPPED:-false}" == "true" ]]; then
+          ssh-agent -k >/dev/null || true
+          if [[ -f "${HOME}/.ssh/cpflow_known_hosts_backup" ]]; then
+            mv -f -- "${HOME}/.ssh/cpflow_known_hosts_backup" "${HOME}/.ssh/known_hosts"
+          elif [[ "${CPFLOW_KNOWN_HOSTS_HAD_ORIGINAL:-}" == "false" ]]; then
+            rm -f "${HOME}/.ssh/known_hosts"
+          fi
+        fi
+
+    - name: Clean up Docker build secrets
+      if: ${{ always() && inputs.docker_build_secrets != '' }}
+      shell: bash
+      env:
+        DOCKER_BUILD_SECRET_DIRECTORY: ${{ steps.build-secrets.outputs.directory }}
+      run: |
+        set -euo pipefail
+        if [[ -n "${DOCKER_BUILD_SECRET_DIRECTORY:-}" ]]; then
+          rm -rf -- "${DOCKER_BUILD_SECRET_DIRECTORY}"
+        fi

data/.github/actions/cpflow-delete-control-plane-app/delete-app.sh

@@ -29,6 +29,9 @@ case "$exists_status" in
       printf '%s\n' "$exists_output"
     fi
     echo "⚠️ Application does not exist: $APP_NAME"
+    echo "🧹 Checking for disposable review app resources: $APP_NAME"
+    cpflow delete -a "$APP_NAME" --org "$CPLN_ORG" --yes
+    echo "✅ Finished disposable review app cleanup: $APP_NAME"
     exit 0
     ;;
   *)

data/.github/actions/cpflow-preview-promotion/action.yml

@@ -0,0 +1,82 @@
+name: Preview Production Promotion
+description: Compare the deployed staging image to the last recorded production release before approval
+inputs:
+  staging_app_name:
+    required: true
+    description: Staging app to read
+  staging_org:
+    required: true
+    description: Normalized staging org
+  primary_workload:
+    required: false
+    default: ""
+    description: Optional primary workload override
+outputs:
+  primary_workload:
+    description: Workload whose staging image was previewed
+    value: ${{ steps.workloads.outputs.primary }}
+  staging_image:
+    description: Captured staging image for approval
+    value: ${{ steps.preview.outputs.staging_image }}
+  production_commit:
+    description: Last recorded production release commit, if available
+    value: ${{ steps.preview.outputs.production_commit }}
+runs:
+  using: composite
+  steps:
+    - name: Resolve primary workload
+      id: workloads
+      env:
+        STAGING_APP_NAME: ${{ inputs.staging_app_name }}
+        PRIMARY_WORKLOAD: ${{ inputs.primary_workload }}
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        ruby - "${STAGING_APP_NAME}" "${PRIMARY_WORKLOAD}" >> "$GITHUB_OUTPUT" <<'RUBY'
+        require "yaml"
+
+        app = ARGV.fetch(0)
+        requested_primary = ARGV.fetch(1, "").to_s.strip
+        data = YAML.safe_load(File.read(".controlplane/controlplane.yml"), aliases: true)
+        apps = data["apps"] || {}
+        app_config = apps[app]
+
+        unless app_config
+          warn "Error: app '#{app}' is not defined under `apps:` in `.controlplane/controlplane.yml`."
+          warn "       Fix the STAGING_APP_NAME repository variable or add the app to controlplane.yml."
+          exit 1
+        end
+
+        workloads = Array(app_config["app_workloads"]).map(&:to_s).reject(&:empty?)
+        workloads = ["rails"] if workloads.empty?
+
+        primary =
+          if requested_primary.empty?
+            if workloads.length == 1
+              workloads.first
+            elsif workloads.include?("rails")
+              "rails"
+            else
+              warn "::error::PRIMARY_WORKLOAD is not configured and app '#{app}' has multiple workloads: #{workloads.join(', ')}."
+              warn "       Set the PRIMARY_WORKLOAD repository variable to one of these workloads."
+              exit 1
+            end
+          elsif workloads.include?(requested_primary)
+            requested_primary
+          else
+            warn "::error::PRIMARY_WORKLOAD '#{requested_primary}' is not one of: #{workloads.join(', ')}."
+            exit 1
+          end
+
+        puts "primary=#{primary}"
+        RUBY
+    - name: Compare recorded production release to staging
+      id: preview
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        STAGING_APP_NAME: ${{ inputs.staging_app_name }}
+        CPLN_ORG_STAGING: ${{ inputs.staging_org }}
+        PRIMARY_WORKLOAD: ${{ steps.workloads.outputs.primary }}
+      shell: bash
+      run: bash "${ACTION_PATH}/preview-promotion.sh"

data/.github/actions/cpflow-preview-promotion/preview-promotion.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This job has only the staging token. Production provenance comes from the
+# successful production-* release record and is checked against the live image
+# by the protected deployment job after approval.
+export GH_HOST="${GITHUB_SERVER_URL#https://}"
+export GH_ENTERPRISE_TOKEN="${GH_TOKEN:-}"
+workload_json="$(cpln workload get "$PRIMARY_WORKLOAD" --gvc "$STAGING_APP_NAME" --org "$CPLN_ORG_STAGING" -o json)"
+staging_image="$(jq -r '.spec.containers[0].image // empty' <<< "$workload_json")"
+if [[ "$staging_image" == /org/*/image/* ]]; then
+  staging_image="${staging_image##*/image/}"
+elif [[ "$staging_image" == *.registry.cpln.io/* ]]; then
+  staging_image="${staging_image#*.registry.cpln.io/}"
+fi
+staging_tag="${staging_image%%@*}"
+staging_commit="${staging_tag##*_}"
+if [[ "$staging_image" == *$'\n'* || "$staging_image" == *$'\r'* ]] || ! [[ "$staging_commit" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "::error::The deployed staging image must include a full lowercase commit SHA suffix."
+  exit 1
+fi
+echo "staging_image=$staging_image" >> "$GITHUB_OUTPUT"
+{
+  echo "## Commits ready for production"
+  echo
+  echo "Preview captured before production approval. Baseline: the last recorded successful production release; live production is verified after approval."
+  echo
+} >> "$GITHUB_STEP_SUMMARY"
+
+# Limit release discovery to the latest 100 entries. Missing provenance is
+# explicit rather than falling back to a moving branch or an unrelated release.
+if ! releases="$(timeout 30s gh api "repos/${GH_REPO}/releases?per_page=100")"; then
+  echo "Comparison unavailable: GitHub could not read the production release history." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+production_release="$(jq -r '[.[] | select(.draft == false and .prerelease == false) | select(.tag_name | test("^production-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{6}-[0-9]+$"))] | sort_by(.published_at // "") | reverse | .[0].tag_name // empty' <<< "$releases")"
+if [[ -z "$production_release" ]]; then
+  echo "Comparison unavailable: no successful production release was found in the latest 100 releases." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+# Resolve the tag itself: target_commitish can be a branch name on older releases.
+if ! production_json="$(timeout 30s gh api "repos/${GH_REPO}/commits/${production_release}")"; then
+  echo "Comparison unavailable: GitHub could not resolve the recorded production release." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+production_commit="$(jq -r '.sha // empty' <<< "$production_json")"
+if ! [[ "$production_commit" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "Comparison unavailable: the recorded production release has no full commit SHA." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+echo "production_commit=$production_commit" >> "$GITHUB_OUTPUT"
+
+repository_url="${GITHUB_SERVER_URL}/${GH_REPO}"
+echo "[Recorded production release](${repository_url}/releases/tag/${production_release})" >> "$GITHUB_STEP_SUMMARY"
+{
+  echo "Recorded production release: [\`${production_commit:0:7}\`](${repository_url}/commit/${production_commit})"
+  echo "Staging: [\`${staging_commit:0:7}\`](${repository_url}/commit/${staging_commit})"
+  echo
+  echo "[Compare production to staging](${repository_url}/compare/${production_commit}...${staging_commit})"
+  echo
+} >> "$GITHUB_STEP_SUMMARY"
+if [[ "${production_commit}" == "${staging_commit}" ]]; then
+  echo "Production and staging use the same commit; there are no commits to promote." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+
+comparison="$(mktemp)"
+trap 'rm -f "$comparison" "${comparison}.summary"' EXIT
+# One bounded page; the compare link provides the complete diff and history.
+if ! timeout 30s gh api "repos/${GH_REPO}/compare/${production_commit}...${staging_commit}?per_page=100&page=1" > "$comparison"; then
+  echo "Commit list unavailable: GitHub could not compare these deployed commits. Use the compare link above." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+
+if ! jq -r --arg repository_url "$repository_url" '
+  "\(.ahead_by) commit(s) on staging that are not in the recorded production release.", "",
+  (if .status == "diverged" or .status == "behind" then
+    "Warning: staging is \(.status); production has \(.behind_by) commit(s) that are not on staging. Review the comparison before treating this as a forward promotion."
+  else empty end), "",
+  "<ul>",
+  (.commits[:100][] |
+    "<li><a href=\"\($repository_url)/commit/\(.sha)\">\(.sha[:7])</a> " +
+    (.commit.message | split("\n")[0] | @html) + "</li>"),
+  "</ul>", "",
+  (if .ahead_by > 100 then "Showing the first 100 commits; use the compare link for the complete list." else empty end)
+' "$comparison" > "${comparison}.summary"; then
+  echo "Commit list unavailable: GitHub returned incomplete comparison data." >> "$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+cat "${comparison}.summary" >> "$GITHUB_STEP_SUMMARY"

data/.github/workflows/cpflow-deploy-review-app.yml

@@ -4,6 +4,12 @@ run-name: "Deploy Review App - PR #${{ github.event.pull_request.number || githu
 
 on:
   workflow_call:
+    inputs:
+      docker_build_extra_args:
+        description: Optional newline-delimited extra docker build tokens, appended to the repository variable.
+        required: false
+        type: string
+        default: ""
     outputs:
       image_built:
         description: Whether this run successfully built the application image.
@@ -12,6 +18,9 @@ on:
       CPLN_TOKEN_STAGING:
         description: Control Plane token for the staging org that owns review apps.
         required: true
+      REVIEW_APP_DOCKER_BUILD_SECRETS:
+        description: Optional newline-delimited id=value secrets passed to review-app builds through BuildKit secret mounts.
+        required: false
       DOCKER_BUILD_SSH_KEY:
         description: Optional SSH key used by Docker builds that fetch private dependencies.
         required: false
@@ -928,7 +937,10 @@ jobs:
           org: ${{ steps.review-config.outputs.cpln_org }}
           commit: ${{ env.PR_SHA }}
           pr_number: ${{ env.PR_NUMBER }}
-          docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+          docker_build_extra_args: |
+            ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+            ${{ inputs.docker_build_extra_args }}
+          docker_build_secrets: ${{ secrets.REVIEW_APP_DOCKER_BUILD_SECRETS }}
           docker_build_ssh_key: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
           docker_build_ssh_known_hosts: ${{ vars.DOCKER_BUILD_SSH_KNOWN_HOSTS }}
           working_directory: app

data/.github/workflows/cpflow-deploy-staging.yml

@@ -5,6 +5,11 @@ run-name: Deploy Control Plane staging app
 on:
   workflow_call:
     inputs:
+      docker_build_extra_args:
+        description: Optional newline-delimited extra docker build tokens, appended to the repository variable.
+        required: false
+        type: string
+        default: ""
       staging_app_branch_default:
         description: Fallback branch name baked into the generated caller workflow.
         required: false
@@ -14,6 +19,9 @@ on:
       CPLN_TOKEN_STAGING:
         description: Control Plane token for the staging org.
         required: true
+      DOCKER_BUILD_SECRETS:
+        description: Optional newline-delimited id=value secrets passed through BuildKit secret mounts.
+        required: false
       DOCKER_BUILD_SSH_KEY:
         description: Optional SSH key used by Docker builds that fetch private dependencies.
         required: false
@@ -123,7 +131,10 @@ jobs:
           app_name: ${{ env.APP_NAME }}
           org: ${{ vars.CPLN_ORG_STAGING }}
           commit: ${{ github.sha }}
-          docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+          docker_build_extra_args: |
+            ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+            ${{ inputs.docker_build_extra_args }}
+          docker_build_secrets: ${{ secrets.DOCKER_BUILD_SECRETS }}
           docker_build_ssh_key: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
           docker_build_ssh_known_hosts: ${{ vars.DOCKER_BUILD_SSH_KNOWN_HOSTS }}