cpflow 5.0.0.rc.1 → 5.0.0

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

@@ -0,0 +1,507 @@
+name: Deploy Review App to Control Plane
+
+run-name: "Deploy Review App - PR #${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}"
+
+on:
+  workflow_call:
+    inputs:
+      control_plane_flow_ref:
+        description: Git ref used to load shared cpflow composite actions.
+        required: false
+        type: string
+        default: main
+
+permissions:
+  contents: read
+  deployments: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: cpflow-review-app-${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  # Match the delete workflow: a cancelled `cpflow deploy-image` mid-rollout can leave the
+  # review app in a partially-deployed state (workload update in progress, rollout not
+  # settled). Let an in-flight deploy finish before the next push starts a new run.
+  cancel-in-progress: false
+
+env:
+  APP_NAME: ${{ vars.REVIEW_APP_PREFIX }}-${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  CPLN_ORG: ${{ vars.CPLN_ORG_STAGING }}
+  PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  PRIMARY_WORKLOAD: ${{ vars.PRIMARY_WORKLOAD }}
+
+jobs:
+  deploy:
+    # Skip synchronize/opened events from fork PRs at the job level — they cannot access
+    # repository secrets anyway, so running any steps just burns billable minutes. Users
+    # can still manually deploy a fork PR via `+review-app-deploy` (gated below by
+    # author_association) or workflow_dispatch.
+    if: |
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       contains(fromJson('["+review-app-deploy","+review-app-deploy\n","+review-app-deploy\r\n"]'), github.event.comment.body) &&
+       contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: React to deploy command
+        if: github.event_name == 'issue_comment'
+        continue-on-error: true
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        with:
+          script: |
+            try {
+              await github.rest.reactions.createForIssueComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: context.payload.comment.id,
+                content: "rocket"
+              });
+            } catch (error) {
+              if (error.status === 422) {
+                core.info("Deploy command reaction already exists.");
+              } else {
+                throw error;
+              }
+            }
+
+      - name: Checkout control-plane-flow actions
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          repository: shakacode/control-plane-flow
+          ref: ${{ inputs.control_plane_flow_ref }}
+          path: .cpflow
+          persist-credentials: false
+
+      - name: Validate required secrets and variables
+        id: config
+        uses: ./.cpflow/.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
+          pull_request_friendly: "true"
+
+      - name: Resolve PR ref and commit
+        if: steps.config.outputs.ready == 'true'
+        id: resolve-pr
+        env:
+          # Route every GitHub-controlled input through env so the run script never
+          # interpolates ${{ ... }} into shell. All values here are GitHub-controlled
+          # (not user-influenced), so this is for consistency with the rest of the
+          # workflow and to quiet actionlint/StepSecurity, not a fix for an
+          # exploitable injection.
+          EVENT_NAME: ${{ github.event_name }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          DISPATCH_PR_NUMBER: ${{ github.event.inputs.pr_number }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          PR_EVENT_NUMBER: ${{ github.event.pull_request.number }}
+          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          case "${EVENT_NAME}" in
+            workflow_dispatch)
+              pr_number="${DISPATCH_PR_NUMBER}"
+              ;;
+            issue_comment)
+              pr_number="${ISSUE_NUMBER}"
+              ;;
+            pull_request)
+              pr_number="${PR_EVENT_NUMBER}"
+              ;;
+            *)
+              echo "Unsupported event type: ${EVENT_NAME}" >&2
+              exit 1
+              ;;
+          esac
+
+          pr_data="$(gh pr view "$pr_number" --json headRefOid,headRepository,headRepositoryOwner)"
+          pr_sha="$(echo "$pr_data" | jq -r '.headRefOid')"
+          pr_repository="$(echo "$pr_data" | jq -r '[.headRepositoryOwner.login, .headRepository.name] | join("/")')"
+          same_repo="false"
+
+          if [[ "$pr_repository" == "$GITHUB_REPOSITORY" ]]; then
+            same_repo="true"
+          fi
+
+          echo "PR_NUMBER=$pr_number" >> "$GITHUB_ENV"
+          echo "APP_NAME=${REVIEW_APP_PREFIX}-$pr_number" >> "$GITHUB_ENV"
+          echo "PR_SHA=$pr_sha" >> "$GITHUB_ENV"
+          echo "same_repo=${same_repo}" >> "$GITHUB_OUTPUT"
+
+      - name: Validate review app deployment source
+        if: steps.config.outputs.ready == 'true'
+        id: source
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          # Same env-routing pattern as Resolve PR ref and commit above: keep all
+          # ${{ ... }} values out of the run script.
+          SAME_REPO: ${{ steps.resolve-pr.outputs.same_repo }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ "${SAME_REPO}" == "true" ]]; then
+            echo "allowed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [[ "${EVENT_NAME}" == "pull_request" ]]; then
+            echo "allowed=false" >> "$GITHUB_OUTPUT"
+            {
+              echo "Review app deploys are skipped for fork pull requests."
+              echo "This workflow builds Docker images with repository secrets, so review app deploys only run for branches in the base repository."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          if [[ "${EVENT_NAME}" == "issue_comment" ]]; then
+            echo "allowed=false" >> "$GITHUB_OUTPUT"
+            {
+              echo "Review app deploys from fork pull requests require a branch in ${GITHUB_REPOSITORY}."
+              echo "This workflow builds Docker images with repository secrets, so comment-triggered deploys only run for branches in the base repository."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          echo "Review app deploys from fork pull requests are not allowed for workflow_dispatch because this workflow uses repository secrets." >&2
+          exit 1
+
+      - name: Checkout PR commit
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          ref: ${{ env.PR_SHA }}
+          path: app
+          persist-credentials: false
+
+      - name: Remove PR checkout Git metadata
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          rm -rf app/.git
+
+      - name: Setup environment
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        uses: ./.cpflow/.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 }}
+          working_directory: app
+
+      - name: Detect release phase support
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        id: release-phase
+        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
+        with:
+          app_name: ${{ env.APP_NAME }}
+          working_directory: app
+
+      - name: Check if review app exists
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        id: check-app
+        working-directory: app
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          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)
+              if [[ -n "${exists_output}" ]]; then
+                printf '%s\n' "${exists_output}"
+              fi
+              echo "exists=true" >> "$GITHUB_OUTPUT"
+              ;;
+            3)
+              if [[ -n "${exists_output}" ]]; then
+                printf '%s\n' "${exists_output}"
+              fi
+              echo "exists=false" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "::error::cpflow exists returned unexpected exit code ${exists_status} for ${APP_NAME}" >&2
+              if [[ -n "${exists_output}" ]]; then
+                printf '%s\n' "${exists_output}" >&2
+              fi
+              exit "${exists_status}"
+              ;;
+          esac
+
+      - name: Skip auto deploy until a review app is created
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && steps.check-app.outputs.exists != 'true' && github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          {
+            echo "Review app ${APP_NAME} does not exist yet."
+            echo "Create it with +review-app-deploy as the PR comment body."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Setup review app if it does not exist yet
+        id: setup-review-app
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && steps.check-app.outputs.exists != 'true' && github.event_name != 'pull_request'
+        working-directory: app
+        shell: bash
+        run: |
+          set -euo pipefail
+          cpflow setup-app -a "${APP_NAME}" --org "${CPLN_ORG}"
+
+      - name: Create initial PR comment
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        id: create-comment
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        with:
+          script: |
+            const body = [
+              "## 🚀 Starting deployment process...",
+              "",
+              `_Preparing review app deployment for PR #${process.env.PR_NUMBER}, commit ${process.env.PR_SHA}_`
+            ].join("\n");
+
+            const result = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: Number(process.env.PR_NUMBER),
+              body
+            });
+            core.setOutput("comment-id", result.data.id);
+
+      - name: Set deployment links
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        with:
+          script: |
+            const workflowUrl = `${process.env.GITHUB_SERVER_URL}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            core.exportVariable("WORKFLOW_URL", workflowUrl);
+            core.exportVariable(
+              "CONSOLE_URL",
+              `https://console.cpln.io/console/org/${process.env.CPLN_ORG}/gvc/${process.env.APP_NAME}/-info`
+            );
+
+      - name: Initialize GitHub deployment
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        id: init-deployment
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        with:
+          script: |
+            const deployment = await github.rest.repos.createDeployment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: process.env.PR_SHA,
+              environment: `review/${process.env.APP_NAME}`,
+              auto_merge: false,
+              required_contexts: [], // intentional: review apps deploy regardless of required status checks
+              description: `Control Plane review app for PR #${process.env.PR_NUMBER}`
+            });
+
+            await github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: deployment.data.id,
+              state: "in_progress",
+              description: "Deployment started"
+            });
+
+            return deployment.data.id;
+
+      - name: Update PR comment with build status
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        env:
+          COMMENT_ID: ${{ steps.create-comment.outputs.comment-id }}
+        with:
+          script: |
+            const commentId = Number(process.env.COMMENT_ID);
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping PR comment update because no comment id was created.");
+              return;
+            }
+
+            const body = [
+              `🏗️ Building Docker image for PR #${process.env.PR_NUMBER}, commit ${process.env.PR_SHA}`,
+              "",
+              `📝 [View Build Logs](${process.env.WORKFLOW_URL})`,
+              `🎮 [Control Plane Console](${process.env.CONSOLE_URL})`
+            ].join("\n");
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body
+            });
+
+      - name: Build Docker image
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: ./.cpflow/.github/actions/cpflow-build-docker-image
+        with:
+          app_name: ${{ env.APP_NAME }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          commit: ${{ env.PR_SHA }}
+          pr_number: ${{ env.PR_NUMBER }}
+          docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+          docker_build_ssh_key: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
+          docker_build_ssh_known_hosts: ${{ vars.DOCKER_BUILD_SSH_KNOWN_HOSTS }}
+          working_directory: app
+
+      - name: Update PR comment with deploy status
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        env:
+          COMMENT_ID: ${{ steps.create-comment.outputs.comment-id }}
+          DEPLOYING_ICON_URL: ${{ vars.REVIEW_APP_DEPLOYING_ICON_URL }}
+        with:
+          script: |
+            const commentId = Number(process.env.COMMENT_ID);
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping PR comment update because no comment id was created.");
+              return;
+            }
+
+            // Pinned to the commit that introduced this SVG for immutability.
+            // To update the icon: update the SVG, replace this SHA, and regenerate user workflows.
+            const DEFAULT_DEPLOYING_ICON_URL = "https://raw.githubusercontent.com/shakacode/control-plane-flow/7632313232b751aaa0bc55a122bf0615ff490345/docs/assets/cpflow-deploying.svg";
+            const configuredDeployingIconUrl = (process.env.DEPLOYING_ICON_URL || "").trim();
+            const isNone = configuredDeployingIconUrl.toLowerCase() === "none";
+            let deployingIconUrl = DEFAULT_DEPLOYING_ICON_URL;
+
+            if (configuredDeployingIconUrl && !isNone) {
+              try {
+                const parsedUrl = new URL(configuredDeployingIconUrl);
+                if (parsedUrl.protocol === "https:") {
+                  deployingIconUrl = parsedUrl.href;
+                } else {
+                  core.warning("Ignoring REVIEW_APP_DEPLOYING_ICON_URL because it must use https://.");
+                }
+              } catch {
+                core.warning("Ignoring REVIEW_APP_DEPLOYING_ICON_URL because it is not a valid URL.");
+              }
+            }
+
+            const deployingIcon = isNone
+              ? "⏳"
+              : `<img src="${deployingIconUrl}" alt="Deploying" width="20" height="20" />`;
+
+            const body = [
+              "## 🚀 Deploying to Control Plane...",
+              "",
+              `${deployingIcon} **Waiting for deployment to be ready...**`,
+              "",
+              `📝 [View Deploy Logs](${process.env.WORKFLOW_URL})`,
+              `🎮 [Control Plane Console](${process.env.CONSOLE_URL})`
+            ].join("\n");
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body
+            });
+
+      - name: Deploy to Control Plane
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        working-directory: app
+        env:
+          RELEASE_PHASE_FLAG: ${{ steps.release-phase.outputs.flag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          deploy_args=(-a "${APP_NAME}")
+          if [[ -n "${RELEASE_PHASE_FLAG}" ]]; then
+            deploy_args+=("${RELEASE_PHASE_FLAG}")
+          fi
+          deploy_args+=(--org "${CPLN_ORG}" --verbose)
+
+          cpflow deploy-image "${deploy_args[@]}"
+
+      - name: Retrieve app URL
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        id: workload
+        working-directory: app
+        shell: bash
+        run: |
+          set -euo pipefail
+          workload_name="${PRIMARY_WORKLOAD:-rails}"
+          workload_url="$(cpln workload get "${workload_name}" --gvc "${APP_NAME}" --org "${CPLN_ORG}" -o json | jq -r '.status.endpoint // empty')"
+          echo "workload_url=${workload_url}" >> "$GITHUB_OUTPUT"
+
+      - name: Finalize deployment status
+        if: always() && steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd
+        env:
+          COMMENT_ID: ${{ steps.create-comment.outputs.comment-id }}
+          DEPLOYMENT_ID: ${{ steps.init-deployment.outputs.result }}
+          APP_URL: ${{ steps.workload.outputs.workload_url }}
+          JOB_STATUS: ${{ job.status }}
+        with:
+          script: |
+            const commentId = Number(process.env.COMMENT_ID);
+            const deploymentId = process.env.DEPLOYMENT_ID;
+            const appUrl = process.env.APP_URL;
+            const success = process.env.JOB_STATUS === "success";
+
+            if (deploymentId) {
+              await github.rest.repos.createDeploymentStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                deployment_id: Number(deploymentId),
+                state: success ? "success" : "failure",
+                environment: `review/${process.env.APP_NAME}`,
+                environment_url: success && appUrl ? appUrl : undefined,
+                log_url: process.env.WORKFLOW_URL,
+                description: success ? "Review app ready" : "Review app deployment failed"
+              });
+            }
+
+            const successBody = [
+              "## 🎉 Deploy Complete!",
+              "",
+              appUrl ? `### [Open Review App](${appUrl})` : "Review app deployed, but no endpoint URL was detected.",
+              "",
+              `_Deployment successful for PR #${process.env.PR_NUMBER}, commit ${process.env.PR_SHA}_`,
+              "",
+              `🎮 [Control Plane Console](${process.env.CONSOLE_URL})`,
+              `📋 [View Completed Action Build and Deploy Logs](${process.env.WORKFLOW_URL})`
+            ].join("\n");
+
+            const failureBody = [
+              "## ❌ Review App Deployment Failed",
+              "",
+              `_Deployment failed for PR #${process.env.PR_NUMBER}, commit ${process.env.PR_SHA}_`,
+              "",
+              `🎮 [Control Plane Console](${process.env.CONSOLE_URL})`,
+              `📋 [View Failed Action Build and Deploy Logs](${process.env.WORKFLOW_URL})`
+            ].join("\n");
+
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping PR comment update because no comment id was created.");
+              return;
+            }
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: success ? successBody : failureBody
+            });

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

@@ -0,0 +1,168 @@
+name: Deploy Staging to Control Plane
+
+run-name: Deploy Control Plane staging app
+
+on:
+  workflow_call:
+    inputs:
+      control_plane_flow_ref:
+        description: Git ref used to load shared cpflow composite actions.
+        required: false
+        type: string
+        default: main
+      staging_app_branch_default:
+        description: Fallback branch name baked into the generated caller workflow.
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+env:
+  APP_NAME: ${{ vars.STAGING_APP_NAME }}
+  CPLN_ORG: ${{ vars.CPLN_ORG_STAGING }}
+  STAGING_APP_BRANCH: ${{ vars.STAGING_APP_BRANCH || inputs.staging_app_branch_default }}
+
+concurrency:
+  group: cpflow-deploy-staging-${{ github.ref_name }}
+  # Match the review-app and delete workflows: a cancelled `cpflow deploy-image` mid-rollout
+  # can leave the staging GVC in a partially-deployed state (some workloads on the new image,
+  # others on the old). Let an in-flight deploy finish before the next push starts a new run.
+  cancel-in-progress: false
+
+jobs:
+  validate-branch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      is_deployable: ${{ steps.check-branch.outputs.is_deployable }}
+    steps:
+      - name: Check whether this branch should deploy staging
+        id: check-branch
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ -n "${STAGING_APP_BRANCH}" ]]; then
+            if [[ "${GITHUB_REF_NAME}" == "${STAGING_APP_BRANCH}" ]]; then
+              echo "is_deployable=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "Branch '${GITHUB_REF_NAME}' does not match STAGING_APP_BRANCH='${STAGING_APP_BRANCH}'"
+              echo "is_deployable=false" >> "$GITHUB_OUTPUT"
+            fi
+          elif [[ "${GITHUB_REF_NAME}" == "main" || "${GITHUB_REF_NAME}" == "master" ]]; then
+            echo "is_deployable=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Branch '${GITHUB_REF_NAME}' is not main/master and no STAGING_APP_BRANCH is configured"
+            echo "is_deployable=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout control-plane-flow actions
+        if: steps.check-branch.outputs.is_deployable == 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          repository: shakacode/control-plane-flow
+          ref: ${{ inputs.control_plane_flow_ref }}
+          path: .cpflow
+          persist-credentials: false
+
+      - name: Validate required secrets and variables
+        if: steps.check-branch.outputs.is_deployable == 'true'
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
+        env:
+          CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+          STAGING_APP_NAME: ${{ vars.STAGING_APP_NAME }}
+        with:
+          required: |
+            secret:CPLN_TOKEN_STAGING
+            variable:CPLN_ORG_STAGING
+            variable:STAGING_APP_NAME
+
+  build:
+    needs: validate-branch
+    if: needs.validate-branch.outputs.is_deployable == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          persist-credentials: false
+
+      - name: Checkout control-plane-flow actions
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          repository: shakacode/control-plane-flow
+          ref: ${{ inputs.control_plane_flow_ref }}
+          path: .cpflow
+          persist-credentials: false
+
+      - name: Setup environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          working_directory: .cpflow
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+
+      - name: Build Docker image
+        uses: ./.cpflow/.github/actions/cpflow-build-docker-image
+        with:
+          app_name: ${{ env.APP_NAME }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          commit: ${{ github.sha }}
+          docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+          docker_build_ssh_key: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
+          docker_build_ssh_known_hosts: ${{ vars.DOCKER_BUILD_SSH_KNOWN_HOSTS }}
+
+  deploy:
+    needs: [validate-branch, build]
+    if: needs.validate-branch.outputs.is_deployable == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          persist-credentials: false
+
+      - name: Checkout control-plane-flow actions
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          repository: shakacode/control-plane-flow
+          ref: ${{ inputs.control_plane_flow_ref }}
+          path: .cpflow
+          persist-credentials: false
+
+      - name: Setup environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          working_directory: .cpflow
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+
+      - name: Detect release phase support
+        id: release-phase
+        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
+        with:
+          app_name: ${{ env.APP_NAME }}
+
+      - name: Deploy staging image
+        env:
+          RELEASE_PHASE_FLAG: ${{ steps.release-phase.outputs.flag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          deploy_args=(-a "${APP_NAME}")
+          if [[ -n "${RELEASE_PHASE_FLAG}" ]]; then
+            deploy_args+=("${RELEASE_PHASE_FLAG}")
+          fi
+          deploy_args+=(--org "${CPLN_ORG}" --verbose)
+
+          cpflow deploy-image "${deploy_args[@]}"