cpflow 4.2.0 → 5.0.0.rc.0

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

@@ -0,0 +1,131 @@
+name: Build Docker Image
+description: Builds and pushes the app image for a Control Plane workload
+
+inputs:
+  app_name:
+    description: Name of the application
+    required: true
+  org:
+    description: Control Plane organization name
+    required: true
+  commit:
+    description: Commit SHA to tag the image with
+    required: true
+  pr_number:
+    description: Pull request number for status messaging
+    required: false
+  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_ssh_key:
+    description: Optional private SSH key used for Docker builds that fetch private dependencies with RUN --mount=type=ssh
+    required: false
+  docker_build_ssh_known_hosts:
+    description: Optional SSH known_hosts entries used with docker_build_ssh_key. Defaults to pinned GitHub.com host keys.
+    required: false
+  working_directory:
+    description: Directory containing the app .controlplane config and Docker build context
+    required: false
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    # 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
+      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.
+        DOCKER_BUILD_SSH_KEY: ${{ inputs.docker_build_ssh_key }}
+        DOCKER_BUILD_SSH_KNOWN_HOSTS: ${{ inputs.docker_build_ssh_known_hosts }}
+      run: |
+        set -euo pipefail
+
+        umask 077
+        mkdir -p ~/.ssh
+        chmod 700 ~/.ssh
+
+        if [[ -n "${DOCKER_BUILD_SSH_KNOWN_HOSTS}" ]]; then
+          printf '%s\n' "${DOCKER_BUILD_SSH_KNOWN_HOSTS}" > ~/.ssh/known_hosts
+        else
+          printf '%s\n' \
+            'github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl' \
+            'github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=' \
+            'github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=' \
+            > ~/.ssh/known_hosts
+        fi
+        chmod 600 ~/.ssh/known_hosts
+
+        printf '%s\n' "${DOCKER_BUILD_SSH_KEY}" > ~/.ssh/cpflow_build_key
+        chmod 600 ~/.ssh/cpflow_build_key
+
+    - name: Build Docker image
+      shell: bash
+      env:
+        APP_NAME: ${{ inputs.app_name }}
+        COMMIT_SHA: ${{ inputs.commit }}
+        CONTROL_PLANE_ORG: ${{ inputs.org }}
+        DOCKER_BUILD_EXTRA_ARGS: ${{ inputs.docker_build_extra_args }}
+        PR_NUMBER: ${{ inputs.pr_number }}
+        WORKING_DIRECTORY: ${{ inputs.working_directory }}
+      run: |
+        set -euo pipefail
+
+        PR_INFO=""
+        docker_build_args=()
+        ssh_agent_started=false
+        build_ssh_prepped=false
+
+        cleanup_build_ssh() {
+          if [[ "${ssh_agent_started}" == "true" ]]; then
+            ssh-agent -k >/dev/null || true
+          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"
+          fi
+        }
+        trap cleanup_build_ssh EXIT
+        cd "${WORKING_DIRECTORY}"
+
+        if [[ -n "${PR_NUMBER}" ]]; then
+          PR_INFO=" for PR #${PR_NUMBER}"
+        fi
+
+        if [[ -n "${DOCKER_BUILD_EXTRA_ARGS}" ]]; then
+          while IFS= read -r arg; do
+            arg="${arg%$'\r'}"
+            [[ -n "${arg}" ]] || continue
+
+            if [[ "${arg}" =~ [[:space:]] ]]; then
+              echo "docker_build_extra_args entries must be single docker-build tokens. " \
+                   "Use key=value forms like --build-arg=FOO=bar." >&2
+              exit 1
+            fi
+
+            docker_build_args+=("${arg}")
+          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"
+          docker_build_args+=("--ssh=default")
+        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})"

data/lib/github_flow_templates/.github/actions/cpflow-delete-control-plane-app/action.yml

@@ -0,0 +1,24 @@
+name: Delete Control Plane App
+description: Deletes a Control Plane app and all associated resources
+
+inputs:
+  app_name:
+    description: Name of the application to delete
+    required: true
+  cpln_org:
+    description: Control Plane organization name
+    required: true
+  review_app_prefix:
+    description: Prefix used for review app names
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Delete application
+      shell: bash
+      run: ${{ github.action_path }}/delete-app.sh
+      env:
+        APP_NAME: ${{ inputs.app_name }}
+        CPLN_ORG: ${{ inputs.cpln_org }}
+        REVIEW_APP_PREFIX: ${{ inputs.review_app_prefix }}

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

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+set -euo pipefail
+
+: "${APP_NAME:?APP_NAME environment variable is required}"
+: "${CPLN_ORG:?CPLN_ORG environment variable is required}"
+: "${REVIEW_APP_PREFIX:?REVIEW_APP_PREFIX environment variable is required}"
+
+expected_prefix="${REVIEW_APP_PREFIX}-"
+if [[ "$APP_NAME" != "${expected_prefix}"* ]]; then
+  echo "❌ ERROR: refusing to delete an app outside the review app prefix" >&2
+  echo "App name: $APP_NAME" >&2
+  echo "Expected prefix: ${expected_prefix}" >&2
+  exit 1
+fi
+
+echo "🔍 Checking if application exists: $APP_NAME"
+exists_output=""
+set +e
+exists_output="$(cpflow exists -a "$APP_NAME" --org "$CPLN_ORG" 2>&1)"
+exists_status=$?
+set -e
+
+case "$exists_status" in
+  0)
+    ;;
+  3)
+    if [[ -n "$exists_output" ]]; then
+      printf '%s\n' "$exists_output"
+    fi
+    echo "⚠️ Application does not exist: $APP_NAME"
+    exit 0
+    ;;
+  *)
+    echo "❌ ERROR: failed to determine whether application exists: $APP_NAME" >&2
+    if [[ -n "$exists_output" ]]; then
+      printf '%s\n' "$exists_output" >&2
+    fi
+    exit "$exists_status"
+    ;;
+esac
+
+if [[ -n "$exists_output" ]]; then
+  printf '%s\n' "$exists_output"
+fi
+
+echo "🗑️ Deleting application: $APP_NAME"
+cpflow delete -a "$APP_NAME" --org "$CPLN_ORG" --yes
+
+echo "✅ Successfully deleted application: $APP_NAME"

data/lib/github_flow_templates/.github/actions/cpflow-detect-release-phase/action.yml

@@ -0,0 +1,62 @@
+name: Detect release phase support
+description: >-
+  Inspects .controlplane/controlplane.yml for an app and emits `flag=--run-release-phase`
+  when a `release_script:` is configured. Outputs an empty `flag` otherwise.
+
+inputs:
+  app_name:
+    description: cpflow app name to inspect
+    required: true
+  working_directory:
+    description: Directory containing .controlplane/controlplane.yml
+    required: false
+    default: "."
+
+outputs:
+  flag:
+    description: Either `--run-release-phase` or empty
+    value: ${{ steps.detect.outputs.flag }}
+
+runs:
+  using: composite
+  steps:
+    - name: Detect release phase support
+      id: detect
+      shell: bash
+      env:
+        APP_NAME: ${{ inputs.app_name }}
+        WORKING_DIRECTORY: ${{ inputs.working_directory }}
+      run: |
+        set -euo pipefail
+        cd "${WORKING_DIRECTORY}"
+
+        release_script="$(ruby - "${APP_NAME}" <<'RUBY'
+        require "yaml"
+
+        app_name = ARGV.fetch(0)
+        data = YAML.safe_load(File.read(".controlplane/controlplane.yml"), aliases: true)
+        apps = data["apps"] || {}
+        app_config = apps[app_name]
+
+        unless app_config
+          app_config = apps.find do |name, config|
+            config.is_a?(Hash) &&
+              config["match_if_app_name_starts_with"] &&
+              app_name.start_with?(name)
+          end&.last
+        end
+
+        unless app_config.is_a?(Hash)
+          warn "Error: app '#{app_name}' is not defined under `apps:` in `.controlplane/controlplane.yml`."
+          exit 1
+        end
+
+        puts app_config["release_script"].to_s
+        RUBY
+        )"
+
+        if [[ -n "${release_script}" ]]; then
+          echo "flag=--run-release-phase" >> "$GITHUB_OUTPUT"
+        else
+          echo "flag=" >> "$GITHUB_OUTPUT"
+        fi

data/lib/github_flow_templates/.github/actions/cpflow-setup-environment/action.yml

@@ -0,0 +1,98 @@
+name: Setup Control Plane Environment
+description: Sets up Ruby, installs the Control Plane CLI and cpflow gem, and configures a default profile
+
+inputs:
+  token:
+    description: Control Plane token
+    required: true
+  org:
+    description: Control Plane organization
+    required: true
+  ruby_version:
+    description: >-
+      Ruby version used for cpflow. When empty (the default), ruby/setup-ruby auto-detects
+      from .ruby-version, .tool-versions, or the Gemfile.
+    required: false
+    default: ""
+  cpln_cli_version:
+    description: >-
+      @controlplane/cli version. Empty string falls back to the action's pinned default
+      so callers can pass `${{ vars.CPLN_CLI_VERSION }}` unconditionally.
+    required: false
+    default: ""
+  cpflow_version:
+    description: >-
+      cpflow gem version. Empty string falls back to the action's pinned default
+      so callers can pass `${{ vars.CPFLOW_VERSION }}` unconditionally.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  # Third-party actions are pinned to floating major tags (`@v4`, `@v1`, `@v7`) rather than
+  # immutable SHAs. SHA pinning is GitHub's stronger security recommendation, but for
+  # generated templates that ship into many downstream repositories floating tags are
+  # easier for users to keep current and Dependabot/Renovate already cover the SHA-pinning
+  # workflow for repositories that opt in. Repositories with stricter supply-chain
+  # requirements should replace each `uses: actions/...@vN` with the corresponding
+  # immutable commit SHA.
+  steps:
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ inputs.ruby_version }}
+
+    - name: Install Control Plane CLI and cpflow gem
+      shell: bash
+      env:
+        CPLN_CLI_VERSION: ${{ inputs.cpln_cli_version }}
+        CPFLOW_VERSION: ${{ inputs.cpflow_version }}
+      run: |
+        set -euo pipefail
+
+        # Bump these defaults when a new release lands that you want to roll out by default.
+        # Override per-repo by setting `CPLN_CLI_VERSION` / `CPFLOW_VERSION` repo variables;
+        # an empty input falls back to the action's pinned default below.
+        default_cpln_cli_version="3.3.1"
+        default_cpflow_version="__CPFLOW_VERSION__"
+
+        CPLN_CLI_VERSION="${CPLN_CLI_VERSION:-${default_cpln_cli_version}}"
+        CPFLOW_VERSION="${CPFLOW_VERSION:-${default_cpflow_version}}"
+
+        npm_global_prefix="${HOME}/.npm-global"
+        mkdir -p "${npm_global_prefix}"
+        echo "${npm_global_prefix}/bin" >> "$GITHUB_PATH"
+        export PATH="${npm_global_prefix}/bin:${PATH}"
+
+        npm install --global --prefix "${npm_global_prefix}" "@controlplane/cli@${CPLN_CLI_VERSION}"
+        cpln --version
+
+        gem install cpflow -v "${CPFLOW_VERSION}" --no-document
+        cpflow --version
+
+    - name: Setup Control Plane profile and registry login
+      shell: bash
+      env:
+        # Pass the token via CPLN_TOKEN so cpln picks it up from the environment
+        # rather than `--token`, which would leak it into /proc/<pid>/cmdline and ps output.
+        CPLN_TOKEN: ${{ inputs.token }}
+        ORG: ${{ inputs.org }}
+      run: |
+        set -euo pipefail
+
+        if [[ -z "$CPLN_TOKEN" ]]; then
+          echo "Error: Control Plane token not provided" >&2
+          exit 1
+        fi
+
+        if [[ -z "$ORG" ]]; then
+          echo "Error: Control Plane organization not provided" >&2
+          exit 1
+        fi
+
+        # `cpln profile update` lists `create` as an alias (cpln profile --help) and is
+        # idempotent: it creates the profile if missing and updates it otherwise. Calling
+        # update directly avoids parsing the CLI's "already exists" English error text,
+        # which would silently swallow a real failure if the wording ever changed.
+        cpln profile update default --org "$ORG"
+        cpln image docker-login --org "$ORG"

data/lib/github_flow_templates/.github/actions/cpflow-validate-config/action.yml

@@ -0,0 +1,85 @@
+name: Validate cpflow GitHub configuration
+description: >-
+  Validates that required secrets and repository variables are set before a workflow
+  proceeds. Pass each value via `env:` with the same NAME as the secret or variable,
+  then list the required entries in `required` as `type:NAME` pairs (type is `secret`
+  or `variable`). When `pull_request_friendly: true` and the current event is a
+  pull request event, missing config writes a step summary and exits 0 with
+  `ready=false` instead of failing the job.
+
+inputs:
+  required:
+    description: |
+      Newline-separated `type:NAME` pairs. Type is `secret` or `variable`. The
+      caller MUST export the matching values via `env:` using the same NAME.
+    required: true
+  pull_request_friendly:
+    description: When "true" and event is pull_request/pull_request_target, write summary and exit 0 with ready=false.
+    required: false
+    default: "false"
+
+outputs:
+  ready:
+    description: '"true" when all values are set, "false" when missing in PR-friendly mode.'
+    value: ${{ steps.check.outputs.ready }}
+
+runs:
+  using: composite
+  steps:
+    - name: Check required secrets and variables
+      id: check
+      shell: bash
+      env:
+        CPFLOW_REQUIRED: ${{ inputs.required }}
+        CPFLOW_PR_FRIENDLY: ${{ inputs.pull_request_friendly }}
+        CPFLOW_EVENT_NAME: ${{ github.event_name }}
+      run: |
+        set -euo pipefail
+
+        missing=()
+        while IFS= read -r entry; do
+          entry="${entry%$'\r'}"
+          entry="${entry## }"
+          entry="${entry%% }"
+          [[ -z "${entry}" ]] && continue
+
+          type="${entry%%:*}"
+          name="${entry#*:}"
+
+          # Reject names that are not plain SHELL_VAR identifiers before doing the
+          # indirect lookup below. Without this guard, ${!name} would expand whatever
+          # bash nameref/transformation a hand-edited generated workflow snuck in
+          # (e.g. `BASH_FUNC_foo%%`). Callers today are the generated templates, but
+          # the generated file lives in the user's repo and can be hand-edited.
+          if [[ ! "${name}" =~ ^[A-Z_][A-Z0-9_]*$ ]]; then
+            echo "Invalid config entry name: ${name}" >&2
+            exit 1
+          fi
+
+          # Indirect bash lookup: reads the env var named by ${name} (e.g. CPLN_TOKEN_STAGING)
+          # so the value never has to round-trip through workflow logs.
+          if [[ -z "${!name:-}" ]]; then
+            missing+=("${type}:${name}")
+          fi
+        done <<< "${CPFLOW_REQUIRED}"
+
+        if [[ ${#missing[@]} -eq 0 ]]; then
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        if [[ "${CPFLOW_PR_FRIENDLY}" == "true" && ( "${CPFLOW_EVENT_NAME}" == "pull_request" || "${CPFLOW_EVENT_NAME}" == "pull_request_target" ) ]]; then
+          echo "ready=false" >> "$GITHUB_OUTPUT"
+          {
+            echo "Control Plane review app automation is not configured yet."
+            echo
+            echo "Missing required GitHub configuration:"
+            printf -- '- `%s`\n' "${missing[@]}"
+            echo
+            echo "Pushes to this pull request will skip review app deploys until the repository is configured."
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit 0
+        fi
+
+        printf 'Missing required GitHub configuration:\n- %s\n' "${missing[@]}" >&2
+        exit 1

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

@@ -0,0 +1,92 @@
+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.
+
+inputs:
+  workload_name:
+    description: Workload to query (e.g. `rails`).
+    required: true
+  app_name:
+    description: GVC / Control Plane app name the workload belongs to.
+    required: true
+  org:
+    description: Control Plane organization.
+    required: true
+  max_retries:
+    description: Number of attempts before giving up.
+    required: false
+    default: "24"
+  interval_seconds:
+    description: Seconds to sleep between attempts.
+    required: false
+    default: "15"
+  accepted_statuses:
+    description: >-
+      Space-separated list of HTTP status codes considered healthy. The default
+      `200 301 302` accepts redirects because curl is invoked without `-L`, so a
+      root path that auth-redirects looks like a redirect, not a failure.
+    required: false
+    default: "200 301 302"
+  curl_max_time:
+    description: Per-request curl timeout, seconds.
+    required: false
+    default: "10"
+
+outputs:
+  healthy:
+    description: '"true" once a healthy response was observed; "false" otherwise.'
+    value: ${{ steps.poll.outputs.healthy }}
+
+runs:
+  using: composite
+  steps:
+    - name: Poll workload endpoint
+      id: poll
+      shell: bash
+      env:
+        CPFLOW_WORKLOAD_NAME: ${{ inputs.workload_name }}
+        CPFLOW_APP_NAME: ${{ inputs.app_name }}
+        CPFLOW_ORG: ${{ inputs.org }}
+        CPFLOW_MAX_RETRIES: ${{ inputs.max_retries }}
+        CPFLOW_INTERVAL_SECONDS: ${{ inputs.interval_seconds }}
+        CPFLOW_ACCEPTED_STATUSES: ${{ inputs.accepted_statuses }}
+        CPFLOW_CURL_MAX_TIME: ${{ inputs.curl_max_time }}
+      run: |
+        set -euo pipefail
+
+        read -r -a accepted_statuses <<< "${CPFLOW_ACCEPTED_STATUSES}"
+
+        for attempt in $(seq 1 "${CPFLOW_MAX_RETRIES}"); do
+          echo "Health check attempt ${attempt}/${CPFLOW_MAX_RETRIES}"
+
+          if ! workload_json="$(cpln workload get "${CPFLOW_WORKLOAD_NAME}" --gvc "${CPFLOW_APP_NAME}" --org "${CPFLOW_ORG}" -o json 2>&1)"; then
+            echo "::error::Workload '${CPFLOW_WORKLOAD_NAME}' not found in GVC '${CPFLOW_APP_NAME}'. Set PRIMARY_WORKLOAD to the correct workload name." >&2
+            printf '%s\n' "${workload_json}" >&2
+            echo "healthy=false" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+
+          endpoint="$(echo "${workload_json}" | jq -r '.status.endpoint // empty')"
+          if [[ -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}"
+
+            for accepted in "${accepted_statuses[@]}"; do
+              if [[ "${http_status}" == "${accepted}" ]]; then
+                echo "healthy=true" >> "$GITHUB_OUTPUT"
+                exit 0
+              fi
+            done
+          else
+            echo "Workload '${CPFLOW_WORKLOAD_NAME}' has no endpoint yet; waiting for one to be assigned."
+          fi
+
+          if [[ "${attempt}" -lt "${CPFLOW_MAX_RETRIES}" ]]; then
+            sleep "${CPFLOW_INTERVAL_SECONDS}"
+          fi
+        done
+
+        echo "healthy=false" >> "$GITHUB_OUTPUT"
+        exit 1

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -0,0 +1,47 @@
+# Control Plane GitHub Flow
+
+## PR commands
+
+`/deploy-review-app`
+- Creates the review app if it does not exist
+- Builds the PR commit image
+- Deploys the image and comments with the review URL
+- Comment body must be exactly `/deploy-review-app` — no surrounding text, trailing whitespace, or trailing newline. The trigger uses an exact-equality match, so a comment like `please /deploy-review-app now` or `/deploy-review-app ` (with a trailing space) silently no-ops.
+
+`/delete-review-app`
+- Deletes the review app when the PR is done
+- This also runs automatically when the PR closes
+- Same exact-match rule as `/deploy-review-app`: the comment body must be exactly `/delete-review-app`.
+
+## Repository secrets
+
+| Name | Required | Notes |
+| --- | --- | --- |
+| `CPLN_TOKEN_STAGING` | yes | Service-account token scoped to the staging org. |
+| `CPLN_TOKEN_PRODUCTION` | yes (for promote) | Service-account token scoped to the production org. |
+| `DOCKER_BUILD_SSH_KEY` | optional | Private SSH key used when Docker builds fetch private deps via `RUN --mount=type=ssh`. |
+
+## Repository variables
+
+| Name | Required | Notes |
+| --- | --- | --- |
+| `CPLN_ORG_STAGING` | yes | Control Plane org for staging and review apps. |
+| `CPLN_ORG_PRODUCTION` | yes (for promote) | Control Plane org for production. |
+| `STAGING_APP_NAME` | yes | App name in `controlplane.yml` used as the staging deploy target. |
+| `PRODUCTION_APP_NAME` | yes (for promote) | App name in `controlplane.yml` used as the production deploy target. |
+| `REVIEW_APP_PREFIX` | yes | Prefix for per-PR review app names (e.g. `review-app`). |
+| `STAGING_APP_BRANCH` | optional | Custom staging branch. Custom branches must also appear in `cpflow-deploy-staging.yml`'s push filter. |
+| `PRIMARY_WORKLOAD` | optional | Workload polled for health and rollback (defaults to `rails`). |
+| `DOCKER_BUILD_EXTRA_ARGS` | optional | Newline-delimited extra docker build tokens (e.g. `--build-arg=FOO=bar`). |
+| `DOCKER_BUILD_SSH_KNOWN_HOSTS` | optional | SSH known_hosts entries when SSH build hosts are not GitHub.com. |
+| `HEALTH_CHECK_ACCEPTED_STATUSES` | optional | Space-separated HTTP statuses considered healthy on promote (default `200 301 302`). |
+| `CPLN_CLI_VERSION` | optional | Pin a specific `@controlplane/cli` version; falls back to the action default when unset. |
+| `CPFLOW_VERSION` | optional | Pin a specific cpflow gem version; falls back to the generated default when unset. |
+
+## Workflow behavior
+
+- Review apps are opt-in and created with `/deploy-review-app`
+- New commits redeploy existing review apps automatically
+- Pushes to the staging branch deploy staging automatically
+- Promotion to production is manual via the Actions tab
+- A nightly workflow removes stale review apps

data/lib/github_flow_templates/.github/workflows/cpflow-cleanup-stale-review-apps.yml

@@ -0,0 +1,56 @@
+name: Cleanup Stale Review Apps
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *"
+
+permissions:
+  contents: read
+
+concurrency:
+  # Single global group: only one cleanup sweep at a time. Independent of review-app
+  # deploy/delete groups (different keys), so cleanup will not block per-PR work.
+  group: cpflow-cleanup-stale-review-apps
+  # A cancelled `cpflow cleanup-stale-apps` can leave half-deleted review apps; let
+  # the in-flight run finish before the next scheduled tick begins.
+  cancel-in-progress: false
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Validate required secrets and variables
+        uses: ./.github/actions/cpflow-validate-config
+        env:
+          CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
+        with:
+          required: |
+            secret:CPLN_TOKEN_STAGING
+            variable:CPLN_ORG_STAGING
+            variable:REVIEW_APP_PREFIX
+
+      - name: Setup environment
+        uses: ./.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+
+      - name: Remove stale review apps
+        env:
+          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          cpflow cleanup-stale-apps -a "${REVIEW_APP_PREFIX}" --org "${CPLN_ORG_STAGING}" --yes