cpflow 5.1.0 → 5.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44479e287fa1f7366a4df86ee7f68176c00f2b6cd2fe59c786e5de6f1143d2b3
-  data.tar.gz: acbf5149907b43cc628d2af8c19572d0ffb5de6d1bae630cb98c14c5ca46d4cc
+  metadata.gz: 183da85ac156c39e59af60c42727a8144e9b23bcc44fcacb3eb6a0498a3ab831
+  data.tar.gz: c801e2e1c97114fbd405494600ad9c637b757256331dd59a4069cc56e59b3934
 SHA512:
-  metadata.gz: 1bf64792213761b8e5af2f44bf18c90c32c2ceeef36c23082afbc34def70d7059bb36747dc696e7bb4236538f3670dc177c9d2b06de68459d1e80634604e088a
-  data.tar.gz: 3c789100969a47e6d7b29efa75fb1b99b799074b89e8cf276dbdf505bab36adec20e010700366e36fc12063426ca80cacf58db3f17253f3dbc241a6533485104
+  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

@@ -110,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 }}
@@ -183,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
@@ -274,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
@@ -316,14 +421,17 @@ 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_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
-          CPLN_UPSTREAM_TOKEN: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_TOKEN_PRODUCTION: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
           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 }}
           STAGING_IMAGE: ${{ steps.staging-image.outputs.image }}
         shell: bash
         run: |
@@ -343,14 +451,82 @@ jobs:
           copy_image_attempts=$((copy_image_retries + 1))
           copy_image_retry_interval=$((10#${COPY_IMAGE_RETRY_INTERVAL}))
 
-          if ! CPLN_TOKEN="${CPLN_TOKEN_STAGING}" cpln image get "${STAGING_IMAGE}" --org "${CPLN_ORG_STAGING}" -o json >/dev/null; then
+          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 cpflow copy-image-from-upstream -a "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" --image "${STAGING_IMAGE}"; then
+            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
@@ -370,10 +546,12 @@ jobs:
             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: |
@@ -383,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[@]}"
@@ -393,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 }}
@@ -403,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
@@ -464,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
@@ -489,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
@@ -531,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: |
           {
@@ -538,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,19 @@ 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
@@ -410,7 +423,8 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.1.0...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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (5.1.0)
+    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" />

data/docs/assets/logo/icon-tile.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-label="Control Plane Flow icon">
+<title>Control Plane Flow icon</title>
+<rect x="64" y="64" width="896" height="896" rx="192" fill="#0B1118" stroke="#26313D" stroke-width="12"/>
+<g fill="none" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M290 650 C330 500 435 430 512 512 C600 606 704 560 746 390" stroke="#2BD7FF" stroke-width="68"/>
+  <path d="M746 390 L688 397" stroke="#2BD7FF" stroke-width="68"/>
+  <path d="M746 390 L731 446" stroke="#2BD7FF" stroke-width="68"/>
+</g>
+<circle cx="290" cy="650" r="92" fill="#8973FF"/>
+<circle cx="512" cy="512" r="92" fill="#70D187"/>
+<circle cx="746" cy="390" r="92" fill="#FFB000"/>
+<circle cx="290" cy="650" r="32" fill="#0B1118" opacity="0.88"/>
+<circle cx="512" cy="512" r="32" fill="#0B1118" opacity="0.88"/>
+<circle cx="746" cy="390" r="32" fill="#0B1118" opacity="0.88"/>
+<path d="M390 730 H612" stroke="#2BD7FF" stroke-width="40" stroke-linecap="round" opacity="0.86"/>
+<path d="M612 730 L555 692 M612 730 L555 768" stroke="#2BD7FF" stroke-width="40" stroke-linecap="round" stroke-linejoin="round" opacity="0.86"/>
+</svg>

data/docs/assets/logo/mark-transparent.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-label="Control Plane Flow icon transparent mark">
+<title>Control Plane Flow icon transparent mark</title>
+<g fill="none" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M290 650 C330 500 435 430 512 512 C600 606 704 560 746 390" stroke="#2BD7FF" stroke-width="68"/>
+  <path d="M746 390 L688 397" stroke="#2BD7FF" stroke-width="68"/>
+  <path d="M746 390 L731 446" stroke="#2BD7FF" stroke-width="68"/>
+</g>
+<circle cx="290" cy="650" r="92" fill="#8973FF"/>
+<circle cx="512" cy="512" r="92" fill="#70D187"/>
+<circle cx="746" cy="390" r="92" fill="#FFB000"/>
+<circle cx="290" cy="650" r="32" fill="#0B1118" opacity="0.88"/>
+<circle cx="512" cy="512" r="32" fill="#0B1118" opacity="0.88"/>
+<circle cx="746" cy="390" r="32" fill="#0B1118" opacity="0.88"/>
+<path d="M390 730 H612" stroke="#2BD7FF" stroke-width="40" stroke-linecap="round" opacity="0.86"/>
+<path d="M612 730 L555 692 M612 730 L555 768" stroke="#2BD7FF" stroke-width="40" stroke-linecap="round" stroke-linejoin="round" opacity="0.86"/>
+</svg>

data/docs/ci-automation.md

@@ -196,6 +196,30 @@ For production promotion, also configure:
 - `CPLN_ORG_PRODUCTION` as a production environment variable, for example `company-production`
 - `PRODUCTION_APP_NAME` as a production environment variable, for example `my-app-production`
 
+Enter GitHub variables such as `CPLN_ORG_STAGING`,
+`CPLN_ORG_PRODUCTION`, `STAGING_APP_NAME`, and `PRODUCTION_APP_NAME`
+as plain single-line values. The generated production promotion workflow trims
+accidental leading/trailing whitespace and line endings from Control Plane org
+names before building registry URLs, but embedded line breaks are rejected
+because they could change the target org name after normalization.
+
+Production promotion copies the exact image currently deployed on the selected
+staging workload. If that staging image is digest-pinned, the digest is used for
+the source copy while the production tag is derived from the tag portion. Tags
+with a `_<commit>` suffix keep that suffix in production; plain numeric tags are
+also valid and promote to the next plain production tag. The copy step uses
+`docker buildx imagetools create --prefer-index=false --tag` with isolated
+Docker credentials, which preserves multi-architecture manifests, preserves
+single-platform manifest format when supported, and avoids pulling image layers
+onto the GitHub Actions runner.
+
+Before copying the image, production promotion compares the environment variable
+names exposed by staging and production at both the GVC level and each configured
+app workload's container level. Variables present in staging are treated as
+required for production, while production-only variables emit warnings. A missing
+production workload variable such as a renderer password or runtime secret fails
+the promotion before the image copy starts.
+
 Do not put `CPLN_TOKEN_PRODUCTION` in repository or organization secrets for
 sensitive production systems. Production promotion intentionally runs as a
 normal caller-repo workflow job with `environment: production`, then checks out
@@ -271,6 +295,12 @@ cpflow setup-app -a my-app-production --org my-org-production --skip-post-creati
 Use production-only runtime secrets and values for the production app. The
 protected GitHub Environment controls who can run the promotion workflow, but
 the production app resources still need to exist before the first promotion.
+After bootstrap, populate the production app secret dictionary with the values
+referenced by `.controlplane/templates`, then run `cpflow apply-template` against
+production when templates change so the workload env references remain persisted.
+Production promotion checks for missing GVC and workload container env names
+before copying the staging image, so a staging-only runtime variable will stop
+the run early instead of deploying an image that cannot boot.
 
 Review apps are different: the generated `+review-app-deploy` workflow creates
 temporary PR apps as needed, including the identity and secret policy binding.
@@ -316,6 +346,17 @@ The standard path is:
 7. Store `CPLN_ORG_PRODUCTION` and `PRODUCTION_APP_NAME` as `production`
    environment variables, or as repository variables only when those names are
    intentionally non-sensitive.
+8. Keep GitHub variable values single-line; a pasted trailing newline is trimmed
+   for Control Plane org names, but embedded line breaks are rejected before
+   deployment, copy, health-check, or rollback steps run.
+9. Bootstrap or re-apply the persistent production app templates before first
+   promotion so app workload container env references and Control Plane secret
+   dictionaries exist in production.
+10. Expect promotion to preserve the selected staging image reference. Digest
+   references are copied by digest, commit-suffixed tags keep the commit suffix,
+   and plain numeric tags remain valid.
+11. Expect production health and rollback readiness polling to require Control
+   Plane `status.ready` and `status.readyLatest` before checking the endpoint.
 
 GitHub only exposes environment secrets to jobs that reference the environment
 after configured protection rules pass. GitHub does not allow a caller job that
@@ -415,8 +456,8 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 
 - Manually promotes the staging artifact to production with a confirmation input.
 - Runs the production job in the `production` GitHub Environment, so configured reviewers approve the job before production environment secrets are available.
-- Verifies that production has the env var names staging expects.
-- Runs a health check against `PRIMARY_WORKLOAD`.
+- Verifies that production has the GVC and app workload container env var names staging expects.
+- Runs a health check against `PRIMARY_WORKLOAD` only after Control Plane reports the latest workload version ready.
 - Attempts a rollback of every configured application workload if the new production image does not come up healthy.
 - Creates a GitHub release after a successful promotion.