cpflow 5.0.4 → 5.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51e0566b72525c5e975b384c12930f95ad5f13faaf1691ccbcca27b0c50a13b4
-  data.tar.gz: 91560ebafb43692488b8996ef5e05799a5621bc6066329a71636b3677d1c63e5
+  metadata.gz: 183da85ac156c39e59af60c42727a8144e9b23bcc44fcacb3eb6a0498a3ab831
+  data.tar.gz: c801e2e1c97114fbd405494600ad9c637b757256331dd59a4069cc56e59b3934
 SHA512:
-  metadata.gz: 89ec31dcc8d5b6b53ee62246ec8b514513101466c2f3751297583a540fad6ac99b4579ff6d13dbd332080313e3c8fb25df527b55d69a3e1037ce35a0625f98a4
-  data.tar.gz: 2f3c85b15e050142703328aa6ef5b24bfd5c6ca32d386c6c2918dee0d1ee4b1a34092980781195f65ca59bacc095d57df24a85a26a5be5e719fd79d6cb205748
+  metadata.gz: d9a96ff2bafc56fa5d735780295c2b100f43bacc39c5726b9171e2f4390799168ed6d08286147d3fda284484488687dd98869d69b3eb1de41b87ca8e211c48ec
+  data.tar.gz: affc08be1954d87d78a3284ba44c44a66617bdd8ddf3d1987f661fbb2751d7897b53feb82c8a1bfa4085e649f6f8dd5222d04f9142ed73b65f1c4b8af3b1eb2d

data/.github/actions/cpflow-wait-for-health/action.yml

@@ -1,8 +1,9 @@
 name: Wait for Control Plane workload health
 description: >-
-  Polls the workload's status endpoint with curl and exits success when the
-  HTTP response status is in the accepted list. Fails non-zero (and reports
-  `healthy=false`) once retries are exhausted.
+  Polls Control Plane until the latest workload version is ready, then checks
+  the workload endpoint with curl. Exits success when the HTTP response status
+  is in the accepted list. Fails non-zero (and reports `healthy=false`) once
+  retries are exhausted.
 
 inputs:
   workload_name:
@@ -68,8 +69,14 @@ runs:
             exit 1
           fi
 
+          workload_ready="$(echo "${workload_json}" | jq -r '.status.ready // false')"
+          latest_ready="$(echo "${workload_json}" | jq -r '.status.readyLatest // false')"
+          readiness_status="$(echo "${workload_json}" | jq -r '.health.readiness // "unknown"')"
           endpoint="$(echo "${workload_json}" | jq -r '.status.endpoint // empty')"
-          if [[ -n "${endpoint}" ]]; then
+
+          if [[ "${workload_ready}" != "true" || "${latest_ready}" != "true" ]]; then
+            echo "Workload status: ready=${workload_ready}, readyLatest=${latest_ready}, readiness=${readiness_status}; waiting for latest deployment."
+          elif [[ -n "${endpoint}" ]]; then
             http_status="$(curl -s -o /dev/null -w '%{http_code}' --max-time "${CPFLOW_CURL_MAX_TIME}" "${endpoint}" 2>/dev/null || echo 000)"
             echo "Endpoint: ${endpoint}, HTTP status: ${http_status}"
 

data/.github/workflows/cpflow-promote-staging-to-production.yml

@@ -39,6 +39,8 @@ env:
   # expose a dedicated health endpoint (e.g. "200" for a plain /health, or "200 401 403"
   # for apps that auth-gate / without redirecting).
   HEALTH_CHECK_ACCEPTED_STATUSES: ${{ vars.HEALTH_CHECK_ACCEPTED_STATUSES || '200 301 302' }}
+  COPY_IMAGE_RETRIES: ${{ vars.COPY_IMAGE_RETRIES || '3' }}
+  COPY_IMAGE_RETRY_INTERVAL: ${{ vars.COPY_IMAGE_RETRY_INTERVAL || '20' }}
   ROLLBACK_READINESS_RETRIES: 24
   ROLLBACK_READINESS_INTERVAL: 15
 
@@ -108,11 +110,58 @@ jobs:
             variable:STAGING_APP_NAME
             variable:PRODUCTION_APP_NAME
 
+      - name: Normalize Control Plane org names
+        id: cpln-orgs
+        env:
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          sanitize_control_plane_name() {
+            local label="$1"
+            local value="$2"
+
+            value="${value#"${value%%[![:space:]]*}"}"
+            value="${value%"${value##*[![:space:]]}"}"
+
+            if [[ "${value}" == *$'\r'* || "${value}" == *$'\n'* ]]; then
+              echo "::error::${label} contains embedded line endings; remove them from the repository variable instead of relying on normalization." >&2
+              exit 1
+            fi
+
+            printf '%s' "${value}"
+          }
+
+          validate_control_plane_org() {
+            local label="$1"
+            local value="$2"
+
+            if ! [[ "${value}" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ ]]; then
+              local display_value
+              display_value="$(printf '%q' "${value}")"
+              echo "::error::${label} (${display_value}) must be a valid Control Plane org name; use lowercase alphanumeric characters and hyphens only, with no leading or trailing hyphen." >&2
+              exit 1
+            fi
+          }
+
+          staging_org="$(sanitize_control_plane_name "CPLN_ORG_STAGING" "${CPLN_ORG_STAGING}")"
+          production_org="$(sanitize_control_plane_name "CPLN_ORG_PRODUCTION" "${CPLN_ORG_PRODUCTION}")"
+
+          validate_control_plane_org "CPLN_ORG_STAGING" "${staging_org}"
+          validate_control_plane_org "CPLN_ORG_PRODUCTION" "${production_org}"
+
+          {
+            echo "staging=${staging_org}"
+            echo "production=${production_org}"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Setup production environment
         uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
-          org: ${{ vars.CPLN_ORG_PRODUCTION }}
+          org: ${{ steps.cpln-orgs.outputs.production }}
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
@@ -181,42 +230,100 @@ jobs:
           CPLN_TOKEN_PRODUCTION: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
           STAGING_APP_NAME: ${{ vars.STAGING_APP_NAME }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
-          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
-          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+          CPLN_ORG_STAGING: ${{ steps.cpln-orgs.outputs.staging }}
+          CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
+          WORKLOAD_NAMES: ${{ steps.workloads.outputs.names }}
         shell: bash
         run: |
           set -euo pipefail
 
-          staging_vars="$(CPLN_TOKEN="${CPLN_TOKEN_STAGING}" cpln gvc get "${STAGING_APP_NAME}" --org "${CPLN_ORG_STAGING}" -o json | jq -r '.spec.env // [] | .[].name' | sort)"
-          production_vars="$(CPLN_TOKEN="${CPLN_TOKEN_PRODUCTION}" cpln gvc get "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" -o json | jq -r '.spec.env // [] | .[].name' | sort)"
+          list_gvc_env_names() {
+            local token="$1"
+            local org="$2"
+            local app="$3"
+
+            CPLN_TOKEN="${token}" cpln gvc get "${app}" --org "${org}" -o json |
+              jq -r '.spec.env // [] | .[] | .name // empty' |
+              sort -u
+          }
+
+          list_workload_env_names() {
+            local token="$1"
+            local org="$2"
+            local app="$3"
+            local workload="$4"
+
+            CPLN_TOKEN="${token}" cpln workload get "${workload}" --gvc "${app}" --org "${org}" -o json |
+              jq -r '.spec.containers // [] | .[] | (.env // [])[]? | .name // empty' |
+              sort -u
+          }
+
+          check_required_vars() {
+            local staging_scope="$1"
+            local production_scope="$2"
+            local missing_message="$3"
+            local staging_vars="$4"
+            local production_vars="$5"
+            local missing_vars
+            local production_only_vars
+
+            if [[ -z "${staging_vars}" ]]; then
+              echo "Staging ${staging_scope} exposes no environment variables; skipping parity check."
+              return
+            fi
 
-          if [[ -z "${staging_vars}" ]]; then
-            echo "Staging GVC exposes no environment variables; skipping parity check."
-            exit 0
-          fi
+            # Treat staging as the promotion source of truth: fail when a variable
+            # present in staging is missing in production. Production-only variables
+            # are allowed, but surface them so teams can spot drift.
+            missing_vars="$(comm -23 <(printf '%s\n' "${staging_vars}") <(printf '%s\n' "${production_vars}"))"
+            production_only_vars="$(comm -13 <(printf '%s\n' "${staging_vars}") <(printf '%s\n' "${production_vars}"))"
 
-          # Treat staging as the promotion source of truth: fail when a variable
-          # present in staging is missing in production. Production-only variables
-          # are allowed, but surface them so teams can spot drift.
-          missing_vars="$(comm -23 <(printf '%s\n' "${staging_vars}") <(printf '%s\n' "${production_vars}"))"
-          production_only_vars="$(comm -13 <(printf '%s\n' "${staging_vars}") <(printf '%s\n' "${production_vars}"))"
+            if [[ -n "${production_only_vars}" ]]; then
+              echo "::warning::Production ${production_scope} has environment variables that are not present in staging:"
+              echo "${production_only_vars}"
+            fi
 
-          if [[ -n "${production_only_vars}" ]]; then
-            echo "::warning::Production has environment variables that are not present in staging:"
-            echo "${production_only_vars}"
-          fi
+            if [[ -n "${missing_vars}" ]]; then
+              echo "::error::${missing_message}"
+              echo "${missing_vars}"
+              env_check_failed=1
+            fi
+          }
+
+          # check_required_vars intentionally mutates env_check_failed in this
+          # shell; keep calls outside subshells so failures aggregate before the
+          # final exit.
+          env_check_failed=0
+
+          staging_vars="$(list_gvc_env_names "${CPLN_TOKEN_STAGING}" "${CPLN_ORG_STAGING}" "${STAGING_APP_NAME}")"
+          production_vars="$(list_gvc_env_names "${CPLN_TOKEN_PRODUCTION}" "${CPLN_ORG_PRODUCTION}" "${PRODUCTION_APP_NAME}")"
+          check_required_vars \
+            "GVC '${STAGING_APP_NAME}'" \
+            "GVC '${PRODUCTION_APP_NAME}'" \
+            "Production GVC '${PRODUCTION_APP_NAME}' is missing environment variables that exist in staging" \
+            "${staging_vars}" \
+            "${production_vars}"
 
-          if [[ -n "${missing_vars}" ]]; then
-            echo "::error::Production is missing environment variables that exist in staging"
-            echo "${missing_vars}"
-            exit 1
-          fi
+          while IFS= read -r workload_name; do
+            [[ -n "${workload_name}" ]] || continue
+
+            staging_workload_vars="$(list_workload_env_names "${CPLN_TOKEN_STAGING}" "${CPLN_ORG_STAGING}" "${STAGING_APP_NAME}" "${workload_name}")"
+            production_workload_vars="$(list_workload_env_names "${CPLN_TOKEN_PRODUCTION}" "${CPLN_ORG_PRODUCTION}" "${PRODUCTION_APP_NAME}" "${workload_name}")"
+            check_required_vars \
+              "workload '${workload_name}'" \
+              "workload '${workload_name}'" \
+              "Production workload '${workload_name}' is missing environment variables that exist in staging" \
+              "${staging_workload_vars}" \
+              "${production_workload_vars}"
+          done < <(tr ',' '\n' <<< "${WORKLOAD_NAMES}")
+
+          exit "${env_check_failed}"
 
       - name: Capture current production image
         id: capture-current
         env:
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
-          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+          CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
           WORKLOAD_NAMES: ${{ steps.workloads.outputs.names }}
           PRIMARY_WORKLOAD: ${{ steps.workloads.outputs.primary }}
         shell: bash
@@ -272,7 +379,7 @@ jobs:
         env:
           CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
           STAGING_APP_NAME: ${{ vars.STAGING_APP_NAME }}
-          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+          CPLN_ORG_STAGING: ${{ steps.cpln-orgs.outputs.staging }}
           WORKLOAD_NAMES: ${{ steps.workloads.outputs.names }}
           PRIMARY_WORKLOAD: ${{ steps.workloads.outputs.primary }}
         shell: bash
@@ -314,22 +421,137 @@ jobs:
 
           echo "image=${staging_image}" >> "$GITHUB_OUTPUT"
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5
+
       - name: Copy image from staging
+        id: copy-image
         env:
-          # Pass the upstream token via env rather than `-t` so it doesn't appear in /proc/<pid>/cmdline.
-          CPLN_UPSTREAM_TOKEN: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_TOKEN_PRODUCTION: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
-          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+          CPLN_ORG_STAGING: ${{ steps.cpln-orgs.outputs.staging }}
+          CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
           STAGING_IMAGE: ${{ steps.staging-image.outputs.image }}
         shell: bash
         run: |
           set -euo pipefail
-          cpflow copy-image-from-upstream -a "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" --image "${STAGING_IMAGE}"
+
+          if ! [[ "${COPY_IMAGE_RETRIES}" =~ ^[0-9]+$ ]]; then
+            echo "::error::COPY_IMAGE_RETRIES must be a non-negative integer."
+            exit 1
+          fi
+
+          if ! [[ "${COPY_IMAGE_RETRY_INTERVAL}" =~ ^[0-9]+$ ]]; then
+            echo "::error::COPY_IMAGE_RETRY_INTERVAL must be a non-negative integer."
+            exit 1
+          fi
+
+          copy_image_retries=$((10#${COPY_IMAGE_RETRIES}))
+          copy_image_attempts=$((copy_image_retries + 1))
+          copy_image_retry_interval=$((10#${COPY_IMAGE_RETRY_INTERVAL}))
+
+          staging_image="${STAGING_IMAGE}"
+          if [[ -z "${staging_image}" ]]; then
+            echo "::error::STAGING_IMAGE is not set or is empty."
+            exit 1
+          fi
+
+          if ! CPLN_TOKEN="${CPLN_TOKEN_STAGING}" cpln image get "${staging_image}" --org "${CPLN_ORG_STAGING}" -o json >/dev/null; then
+            echo "::error::Staging image '${STAGING_IMAGE}' was not found in org '${CPLN_ORG_STAGING}'; aborting promotion."
+            exit 1
+          fi
+
+          staging_tag=""
+          if [[ "${staging_image}" == *@* ]]; then
+            staging_tag="${staging_image##*@}"
+          elif [[ "${staging_image}" == *:* ]]; then
+            staging_tag="${staging_image##*:}"
+          fi
+          staging_commit=""
+          if [[ "${staging_tag}" == *_* ]]; then
+            staging_commit="${staging_tag##*_}"
+          else
+            echo "::warning::Staging image '${staging_image}' did not include a '_<commit>' suffix; production image tag will omit the commit suffix."
+          fi
+
+          # The workflow-level concurrency group serializes this sequence so two
+          # production promotions cannot derive and publish the same next tag.
+          # See the top-level concurrency group: cpflow-promote-staging-to-production.
+          latest_number="$(
+            cpln image query --org "${CPLN_ORG_PRODUCTION}" --prop "name~${PRODUCTION_APP_NAME}:" --max 0 -o json |
+              jq -r --arg prefix "${PRODUCTION_APP_NAME}:" \
+                '[.items[].name | select(startswith($prefix)) | (try capture("^[^:]+:(?<number>[0-9]+)") catch empty) | .number | tonumber] | max // 0'
+          )"
+          if ! [[ "${latest_number}" =~ ^[0-9]+$ ]]; then
+            echo "::error::Could not determine the next production image number for app '${PRODUCTION_APP_NAME}' in org '${CPLN_ORG_PRODUCTION}'."
+            exit 1
+          fi
+
+          production_image="${PRODUCTION_APP_NAME}:$((latest_number + 1))"
+          if [[ -n "${staging_commit}" ]]; then
+            production_image="${production_image}_${staging_commit}"
+          fi
+
+          staging_registry="${CPLN_ORG_STAGING}.registry.cpln.io"
+          production_registry="${CPLN_ORG_PRODUCTION}.registry.cpln.io"
+          source_image_ref="${staging_registry}/${STAGING_IMAGE}"
+          production_image_ref="${production_registry}/${production_image}"
+
+          docker_config_dir="$(mktemp -d)"
+          cleanup_copy_credentials() {
+            rm -rf "${docker_config_dir}"
+          }
+          trap cleanup_copy_credentials EXIT
+
+          export DOCKER_CONFIG="${docker_config_dir}"
+
+          if ! printf '%s' "${CPLN_TOKEN_STAGING}" |
+            docker login "${staging_registry}" -u '<token>' --password-stdin >/dev/null; then
+            echo "::error::Failed to authenticate to staging registry '${staging_registry}'."
+            exit 1
+          fi
+
+          if ! printf '%s' "${CPLN_TOKEN_PRODUCTION}" |
+            docker login "${production_registry}" -u '<token>' --password-stdin >/dev/null; then
+            echo "::error::Failed to authenticate to production registry '${production_registry}'."
+            exit 1
+          fi
+
+          if docker buildx imagetools inspect "${production_image_ref}" >/dev/null 2>&1; then
+            echo "::error::Production image '${production_image}' already exists in org '${CPLN_ORG_PRODUCTION}'; aborting to avoid overwriting it."
+            exit 1
+          fi
+
+          copy_status=1
+          for attempt in $(seq 1 "${copy_image_attempts}"); do
+            if docker buildx imagetools inspect "${source_image_ref}" >/dev/null &&
+              docker buildx imagetools create --prefer-index=false --tag "${production_image_ref}" "${source_image_ref}"; then
+              copy_status=0
+              break
+            else
+              copy_status=$?
+            fi
+
+            if [[ "${attempt}" -lt "${copy_image_attempts}" ]]; then
+              echo "::warning::Image copy attempt ${attempt}/${copy_image_attempts} failed with exit ${copy_status}; retrying in ${copy_image_retry_interval}s."
+              sleep "${copy_image_retry_interval}"
+            else
+              echo "::warning::Image copy attempt ${attempt}/${copy_image_attempts} failed with exit ${copy_status}; no attempts remain."
+            fi
+          done
+
+          if [[ "${copy_status}" -ne 0 ]]; then
+            echo "::error::Could not copy staging image '${STAGING_IMAGE}' from '${CPLN_ORG_STAGING}' to '${CPLN_ORG_PRODUCTION}' after ${copy_image_attempts} attempt(s)."
+            exit "${copy_status}"
+          fi
+
+          echo "image=${production_image}" >> "$GITHUB_OUTPUT"
 
       - name: Deploy image to production
         env:
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
-          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+          CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
           RELEASE_PHASE_FLAG: ${{ steps.release-phase.outputs.flag }}
         shell: bash
         run: |
@@ -339,6 +561,9 @@ jobs:
           if [[ -n "${RELEASE_PHASE_FLAG}" ]]; then
             deploy_args+=("${RELEASE_PHASE_FLAG}")
           fi
+          # `cpflow deploy-image` deploys the latest image for the app. The
+          # workflow-level concurrency group keeps production promotion copy and
+          # deploy steps coupled across workflow runs.
           deploy_args+=(--org "${CPLN_ORG_PRODUCTION}" --verbose)
 
           cpflow deploy-image "${deploy_args[@]}"
@@ -349,7 +574,7 @@ jobs:
         with:
           workload_name: ${{ steps.workloads.outputs.primary }}
           app_name: ${{ vars.PRODUCTION_APP_NAME }}
-          org: ${{ vars.CPLN_ORG_PRODUCTION }}
+          org: ${{ steps.cpln-orgs.outputs.production }}
           max_retries: ${{ env.HEALTH_CHECK_RETRIES }}
           interval_seconds: ${{ env.HEALTH_CHECK_INTERVAL }}
           accepted_statuses: ${{ env.HEALTH_CHECK_ACCEPTED_STATUSES }}
@@ -359,7 +584,7 @@ jobs:
         env:
           ROLLBACK_STATE: ${{ steps.capture-current.outputs.rollback_state }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
-          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+          CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
         shell: bash
         run: |
           # Best-effort rollback: try every workload, aggregate failures, exit non-zero at the end
@@ -391,19 +616,14 @@ jobs:
               continue
             fi
 
-            if ! rollback_container_entries="$(
-              jq -r \
-                --argjson current_names "${current_names}" \
-                '.[] as $container | ($current_names | index($container.name)) as $index | "\($index)\t\($container.image)"' \
-                <<< "${previous_containers}"
-            )"; then
+            if ! rollback_container_entries="$(jq -r '.[] | "\(.name)\t\(.image)"' <<< "${previous_containers}")"; then
               echo "::warning::Could not build rollback image list for workload '${workload_name}'; skipping rollback for this workload." >&2
               rollback_failures=$((rollback_failures + 1))
               continue
             fi
 
-            while IFS=$'\t' read -r index image; do
-              rollback_args+=(--set "spec.containers[${index}].image=${image}")
+            while IFS=$'\t' read -r container_name image; do
+              rollback_args+=(--set "spec.containers.${container_name}.image=${image}")
             done <<< "${rollback_container_entries}"
 
             if ! cpln workload update "${workload_name}" \
@@ -425,7 +645,7 @@ jobs:
         env:
           ROLLBACK_STATE: ${{ steps.capture-current.outputs.rollback_state }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
-          CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
+          CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
         shell: bash
         run: |
           set -euo pipefail
@@ -450,8 +670,10 @@ jobs:
               set -euo pipefail
               ready=false
               for attempt in $(seq 1 "${ROLLBACK_READINESS_RETRIES}"); do
-                deployment_ready="$(cpln workload get "${workload_name}" --gvc "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" -o json | jq -r '.status.ready // false')"
-                if [[ "${deployment_ready}" == "true" ]]; then
+                workload_status="$(cpln workload get "${workload_name}" --gvc "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" -o json)"
+                deployment_ready="$(echo "${workload_status}" | jq -r '.status.ready // false')"
+                latest_ready="$(echo "${workload_status}" | jq -r '.status.readyLatest // false')"
+                if [[ "${deployment_ready}" == "true" && "${latest_ready}" == "true" ]]; then
                   ready=true
                   break
                 fi
@@ -492,6 +714,7 @@ jobs:
           HEALTHY: ${{ steps.health-check.outputs.healthy }}
           PREVIOUS_IMAGE: ${{ steps.capture-current.outputs.current_image }}
           PREVIOUS_VERSION: ${{ steps.capture-current.outputs.current_version }}
+          COPIED_IMAGE: ${{ steps.copy-image.outputs.image }}
         shell: bash
         run: |
           {
@@ -499,12 +722,15 @@ jobs:
             echo
             if [[ "${HEALTHY}" == "true" ]]; then
               echo "✅ Status: deployment successful"
+              deployed_image="${COPIED_IMAGE}"
             else
               echo "❌ Status: deployment failed"
+              deployed_image="${PREVIOUS_IMAGE}"
             fi
             echo
             echo "Previous image: \`${PREVIOUS_IMAGE}\`"
             echo "Previous version: ${PREVIOUS_VERSION}"
+            echo "Deployed image: \`${deployed_image}\`"
           } >> "$GITHUB_STEP_SUMMARY"
 
   create-github-release:

data/.github/workflows/rspec-shared.yml

@@ -19,8 +19,15 @@ on:
 jobs:
   rspec:
     runs-on: ${{ inputs.os_version }}
+    # Scope the live Control Plane org queue per PR (or ref) instead of globally:
+    # each run uses its own random app suffix (SecureRandom.hex(2)) on a fresh
+    # runner, so concurrent PRs don't collide on app names or CLI profiles. PRs
+    # run only the fast (~slow) suite, which doesn't switch the shared domain's
+    # route; domain-mutating specs are :slow and dispatched manually, keyed by
+    # github.ref so same-ref dispatches still serialize. cancel-in-progress is
+    # false, so queued runs wait their turn rather than being cancelled.
     concurrency:
-      group: cpln-shared-org-${{ vars.CPLN_ORG || github.run_id }}
+      group: cpln-shared-org-${{ vars.CPLN_ORG || github.run_id }}-${{ github.event.pull_request.number || github.ref }}
       cancel-in-progress: false
     env:
       RAILS_ENV: test

data/CHANGELOG.md

@@ -12,6 +12,31 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [5.1.1] - 2026-06-03
+
+### Changed
+
+- **Changed `cpflow maintenance:on` and `cpflow maintenance:off` to confirm the domain route has switched by polling the Control Plane API (bounded retry, 30 attempts, 1 second apart) instead of sleeping a fixed 30 seconds.** [PR 337](https://github.com/shakacode/control-plane-flow/pull/337) by [Justin Gordon](https://github.com/justin808). Fixes [issue 157](https://github.com/shakacode/control-plane-flow/issues/157). If the route never updates within the poll window, the command aborts before stopping workloads so traffic stays on the current workload, and transient API errors during polling are retried rather than aborting the switch. Because the route switch and the workload stop run as separate steps, re-running the command also finishes a switch whose poll timed out after the route had already updated.
+- **Reworked generated production-promotion image copy to authenticate directly to the staging and production Docker registries and copy via `docker buildx imagetools create`, handling digest-pinned, plain numeric, commit-suffixed, and multi-arch image refs.** [PR 356](https://github.com/shakacode/control-plane-flow/pull/356) by [Justin Gordon](https://github.com/justin808). Promotion now normalizes Control Plane org variables before each step, preflights environment-variable parity between staging and production at the GVC and app-workload container level (failing before the copy when production is missing names that exist in staging), and requires both `status.ready` and `status.readyLatest` before endpoint health checks and rollback polling so a stale ready replica cannot mask a failed latest revision.
+- **Generated production promotion now emits a workflow warning when a staging image tag lacks a `_<commit>` suffix**, so production tags without commit traceability are visible in logs, and documents the `cpflow-promote-staging-to-production` concurrency group in the copy step. [PR 360](https://github.com/shakacode/control-plane-flow/pull/360) by [Justin Gordon](https://github.com/justin808).
+- **Restored review-app security guidance in generated `.github/cpflow-help.md`** (public-repo staging-token scoping, fork-PR deploy limits, secret exposure via `cpln://secret/...`, and read-only deploy keys for `DOCKER_BUILD_SSH_KEY`), and simplified the promotion workflow's staging image assignment while preserving digest refs. [PR 359](https://github.com/shakacode/control-plane-flow/pull/359) by [Justin Gordon](https://github.com/justin808).
+
+### Fixed
+
+- **Fixed `cpflow run` so short non-interactive runner jobs no longer hang when the Control Plane cron job finishes before a runner replica is visible.** [PR 361](https://github.com/shakacode/control-plane-flow/pull/361) by [Justin Gordon](https://github.com/justin808). This prevents generated deploy workflows with release-phase commands from waiting until the GitHub Actions job timeout even though the release job already completed successfully.
+
+## [5.1.0] - 2026-06-02
+
+### Added
+
+- **Added `shared_secret_grants` configuration so apps can reference org-level Control Plane secrets by name instead of hardcoding them in templates.** [PR 354](https://github.com/shakacode/control-plane-flow/pull/354) by [Justin Gordon](https://github.com/justin808). Each grant validates a unique placeholder, a safe Control Plane resource name, and a secret policy that targets exactly that secret; templates gain `{{SHARED_SECRET_<NAME>}}` substitution, and the shared-policy lifecycle is wired through `setup-app`, `deploy-image`, `delete`, and `cleanup-stale-apps`. Enables the shared staging-database pattern for cheaper review apps.
+
+### Fixed
+
+- **Fixed `cpflow generate-github-actions` so the generated `.github/cpflow-help.md` version-locking example derives a `CPFLOW_VERSION=<major>.<minor>.x` placeholder from the installed gem version instead of a hardcoded release that goes stale against the `@v<version>` wrapper refs in the same file.** [PR 343](https://github.com/shakacode/control-plane-flow/pull/343) by [Justin Gordon](https://github.com/justin808). Fixes [issue 341](https://github.com/shakacode/control-plane-flow/issues/341).
+- **Fixed generated production promotion so `cpflow-promote-staging-to-production.yml` runs as a caller-owned job with `environment: production`, letting GitHub inject the `CPLN_TOKEN_PRODUCTION` environment secret after the protected gate instead of failing because a cross-repo reusable workflow cannot receive caller environment secrets.** [PR 353](https://github.com/shakacode/control-plane-flow/pull/353) by [Justin Gordon](https://github.com/justin808). The job checks out the pinned `control-plane-flow` ref into `.cpflow`, and generated help plus `docs/ci-automation.md` now explain why a same-named repository or organization secret can mask a missing environment secret.
+- **Hardened generated production promotion image copy to preflight the staging image, retry the copy via configurable `COPY_IMAGE_RETRIES` and `COPY_IMAGE_RETRY_INTERVAL` repo vars, and roll back failed deploys using `spec.containers.<name>.image` paths instead of unsupported array-index paths.** [PR 355](https://github.com/shakacode/control-plane-flow/pull/355) by [Justin Gordon](https://github.com/justin808).
+
 ## [5.0.4] - 2026-05-27
 
 ### Fixed
@@ -398,7 +423,9 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.4...HEAD
+[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.1.1...HEAD
+[5.1.1]: https://github.com/shakacode/control-plane-flow/compare/v5.1.0...v5.1.1
+[5.1.0]: https://github.com/shakacode/control-plane-flow/compare/v5.0.4...v5.1.0
 [5.0.4]: https://github.com/shakacode/control-plane-flow/compare/v5.0.3...v5.0.4
 [5.0.3]: https://github.com/shakacode/control-plane-flow/compare/v5.0.2...v5.0.3
 [5.0.2]: https://github.com/shakacode/control-plane-flow/compare/v5.0.1...v5.0.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (5.0.4)
+    cpflow (5.1.1)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)

data/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./docs/assets/logo/icon-tile.svg" alt="Control Plane Flow (cpflow) logo" width="160" height="160" />
+</p>
+
 # The power of Kubernetes with the ease of Heroku!
 
 <meta name="author" content="Justin Gordon and Sergey Tarasov" />
@@ -241,6 +245,18 @@ aliases:
     #   it would be 'my-app-review-secrets-policy'
     secrets_policy_name: my-secrets-policy
 
+    # Optional: grant each app identity access to shared org-level secrets
+    # without hardcoding shared secret names in workload templates.
+    #
+    # This is useful for review apps that share one staging database secret
+    # instead of provisioning a database per PR. Create the shared secret and
+    # policy once, then reference the secret in templates with
+    # {{SHARED_SECRET_DATABASE}}.
+    # shared_secret_grants:
+    #   - name: database
+    #     secret_name: my-shared-database-secrets
+    #     policy_name: my-shared-database-secrets-policy
+
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
     one_off_workload: rails
 
@@ -500,6 +516,11 @@ aws-rds-single-pg-instance
   mydb-review-333
 ```
 
+For production, you'll typically want RDS or Aurora in private subnets, reached from your Control Plane workloads
+over a private network path rather than the public internet. See
+[Connecting Control Plane workloads to a private AWS RDS/Aurora database](./docs/rds-private-networking.md) for the
+full Cloud Wormhole + Agent setup.
+
 If you want to run PostgreSQL on Control Plane instead of keeping a Heroku add-on or moving to RDS, review the
 [Control Plane PostgreSQL Template Catalog page](https://shakadocs.controlplane.com/template-catalog/templates/postgres). It includes
 persistent storage and optional scheduled backups. Additionally, we provide a default `postgres` template in this
@@ -565,17 +586,21 @@ cpflow --help
 
 ## Mapping of Heroku Commands to `cpflow` and `cpln`
 
-| Heroku Command                                                                                                 | `cpflow` or `cpln`                 |
-| -------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type)                     | `cpflow ps`                        |
-| [heroku config](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-config)                       | ?                               |
-| [heroku maintenance](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-maintenance)             | `cpflow maintenance`               |
-| [heroku logs](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-logs)                           | `cpflow logs`                      |
-| [heroku pg](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pg-database)                      | ?                               |
-| [heroku pipelines:promote](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pipelines-promote) | `cpflow promote-app-from-upstream` |
-| [heroku psql](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-psql-database)                  | ?                               |
-| [heroku redis](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-redis-database)                | ?                               |
-| [heroku releases](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-releases)                   | ?                               |
+| Heroku Command                                                                                                 | `cpflow` or `cpln`                                                                                                                                                                    |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type)                     | `cpflow ps`                                                                                                                                                                           |
+| [heroku config](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-config)                       | `cpflow env -a APP_NAME` displays Control Plane app environment variables; `cpflow config -a APP_NAME` displays local `.controlplane/controlplane.yml` settings                     |
+| [heroku maintenance](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-maintenance)             | `cpflow maintenance`, `cpflow maintenance:on`, `cpflow maintenance:off`, and `cpflow maintenance:set-page`                                                                            |
+| [heroku logs](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-logs)                           | `cpflow logs -a APP_NAME`; add `-w WORKLOAD_NAME` to filter by workload, or `-w WORKLOAD_NAME -r REPLICA_NAME` to narrow to a specific replica                                        |
+| [heroku pg](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pg-database)                      | No direct `cpflow` add-on wrapper. Use an external Postgres provider, the Control Plane Template Catalog, or project templates such as `.controlplane/templates/postgres.yml`.        |
+| [heroku pipelines:promote](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pipelines-promote) | `cpflow promote-app-from-upstream`                                                                                                                                                    |
+| [heroku psql](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-psql-database)                  | No direct `cpflow` equivalent. Connect with your provider's `psql` flow, or run `cpflow run -a APP_NAME -- psql "$DATABASE_URL"` when `psql` is available in the application image. |
+| [heroku redis](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-redis-database)                | No direct `cpflow` add-on wrapper. Use an external Redis provider, the Control Plane Template Catalog, or project templates such as `.controlplane/templates/redis.yml`.              |
+| [heroku releases](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-releases)                   | `cpflow latest-image -a APP_NAME` for the latest image tag; `cpflow deploy-image -a APP_NAME` deploys that image. No `cpflow` equivalent for browsing full release history.          |
+
+Unlike Heroku add-ons, Control Plane database and cache services are usually managed as provider resources or workload
+templates. `cpflow` focuses on the application deployment flow and leaves provider-specific database administration to
+the provider tooling, Control Plane templates, or direct `cpln` operations.
 
 ## Examples