gcp_backend.yml

name: Deploy Backend to Cloud RUN

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Select the environment to deploy to'
        required: true
        default: 'development'
      release_sha:
        description: 'Exact main SHA with a successful Release Eligibility proof (deploy mode only)'
        required: false
        default: ''
      release_version:
        description: 'Release version (optional)'
        required: false
        default: ''
      mode:
        description: 'Workflow mode'
        required: true
        default: 'deploy'
        type: choice
        options:
          - deploy
          - repair-traffic-only
      deploy_targets:
        description: 'Deploy all backend surfaces or Cloud Run only'
        required: true
        default: 'cloud-run-only'
        type: choice
        options:
          - all
          - cloud-run-only
      deploy_gateway:
        description: 'Development only: deploy the LLM gateway binary with the backend stack (requires deploy_targets=all)'
        required: true
        default: false
        type: boolean
      # Break-glass: the eligibility proof requires a *successful* Release
      # Eligibility push-run on this exact SHA. A flaky or red check therefore
      # poisons that SHA permanently -- rerunning does not retroactively make
      # the original run succeed, so the only other recovery is pushing a new
      # commit to main and waiting for a full green run. That is unacceptable
      # for a hotfix, so this hatch exists.
      #
      # It does NOT relax the property that matters: the SHA must still be an
      # ancestor of main, so unreviewed code can never reach production.
      skip_eligibility_proof:
        description: 'Break-glass: deploy without a Release Eligibility proof (still requires a merged main SHA)'
        required: false
        default: false
        type: boolean
      break_glass_confirm:
        description: 'Type deploy-without-proof when skip_eligibility_proof is set'
        required: false
        default: ''
      break_glass_reason:
        description: 'Why the eligibility proof is unavailable (required with skip_eligibility_proof)'
        required: false
        default: ''

# Cloud Run revision promotion/traffic repair and the shared backend GKE resources
# are one environment-scoped mutation domain across the backend deploy workflows.
concurrency:
  group: deploy-backend-stack-${{ github.event.inputs.environment }}
  cancel-in-progress: false

env:
  SERVICE: backend
  REGION: us-central1
  # Development keeps its existing tagged no-traffic candidate probe. Production
  # instead validates the exact serving release after its rollback-safe shift.
  TRANSCRIPTION_CANDIDATE_TAG: stt-gate-${{ github.run_id }}-${{ github.run_attempt }}

jobs:
  validate-production-boundary:
    if: >-
      github.event.inputs.mode == 'deploy'
    runs-on: ubuntu-latest
    steps:
      - name: Reject unsupported production deployment boundary before side effects
        env:
          DEPLOY_ENVIRONMENT: ${{ github.event.inputs.environment }}
          DEPLOY_TARGETS: ${{ github.event.inputs.deploy_targets }}
        run: |
          set -euo pipefail
          if [[ "$DEPLOY_ENVIRONMENT" != "development" && "$DEPLOY_ENVIRONMENT" != "prod" ]]; then
            echo "Invalid environment: $DEPLOY_ENVIRONMENT. Must be 'development' or 'prod'." >&2
            exit 1
          fi
          if [[ "$DEPLOY_TARGETS" != "all" && "$DEPLOY_TARGETS" != "cloud-run-only" ]]; then
            echo "Invalid deploy_targets: $DEPLOY_TARGETS. Must be 'all' or 'cloud-run-only'." >&2
            exit 1
          fi
          if [[ "$DEPLOY_ENVIRONMENT" == "prod" && "$DEPLOY_TARGETS" == "all" ]]; then
            echo "environment=prod, deploy_targets=all is unsupported; use cloud-run-only." >&2
            exit 1
          fi
          if [[ "${{ github.event.inputs.deploy_gateway }}" == "true" && "$DEPLOY_ENVIRONMENT" == "prod" ]]; then
            echo "environment=prod, deploy_gateway=true is unsupported; use the standalone manual LLM gateway workflow." >&2
            exit 1
          fi
          if [[ "${{ github.event.inputs.deploy_gateway }}" == "true" && "$DEPLOY_TARGETS" != "all" ]]; then
            echo "deploy_gateway=true requires deploy_targets=all." >&2
            exit 1
          fi

  repair-traffic:
    if: >-
      github.ref == 'refs/heads/main' &&
      github.event.inputs.mode == 'repair-traffic-only'
    environment: ${{ github.event.inputs.environment }}
    permissions:
      contents: 'read'
      id-token: 'write'
    runs-on: ubuntu-latest-m
    steps:
      - name: Validate Environment Input
        run: |
          if [[ "${{ github.event.inputs.environment }}" != "development" && "${{ github.event.inputs.environment }}" != "prod" ]]; then
            echo "Invalid environment: ${{ github.event.inputs.environment }}. Must be 'development' or 'prod'."
            exit 1
          fi

      - name: Checkout
        uses: actions/checkout@v7
        with:
          # Traffic repair changes no source-derived runtime state. It stays a
          # separate recovery path and does not consume a release proof.
          ref: main

      - name: Google Auth
        id: auth
        uses: 'google-github-actions/auth@v3'
        with:
          credentials_json: ${{ secrets.GCP_CREDENTIALS }}

      - name: Set up gcloud
        uses: google-github-actions/setup-gcloud@v3

      - name: Restore Cloud Run traffic spec to currently serving revisions
        run: |
          python3 backend/scripts/repair_cloud_run_traffic.py \
            --project=${{ vars.GCP_PROJECT_ID }} \
            --region=${{ env.REGION }} \
            --repair

      - name: Cloud Run deploy status report
        if: always()
        run: |
          python3 backend/scripts/deploy_status_report.py \
            --env ${{ vars.ENV }} \
            --project ${{ vars.GCP_PROJECT_ID }} \
            --region ${{ env.REGION }} \
            --include-cloud-run \
            --cloud-run-service backend \
            --cloud-run-service backend-sync \
            --cloud-run-service backend-sync-backfill \
            --cloud-run-service backend-integration || true

  firestore_readiness:
    needs: validate-production-boundary
    if: >-
      github.ref == 'refs/heads/main' &&
      github.event.inputs.mode == 'deploy'
    environment: ${{ github.event.inputs.environment }}
    permissions:
      actions: 'read'
      contents: 'read'
    runs-on: ubuntu-latest-m
    outputs:
      admitted_sha: ${{ steps.admitted_source.outputs.admitted_sha }}
      break_glass: ${{ steps.admitted_source.outputs.break_glass }}
    steps:
      - name: Validate Firestore readiness inputs
        env:
          DEPLOY_ENVIRONMENT: ${{ github.event.inputs.environment }}
        run: |
          set -euo pipefail
          if [[ "$DEPLOY_ENVIRONMENT" != "development" && "$DEPLOY_ENVIRONMENT" != "prod" ]]; then
            echo "Invalid environment: $DEPLOY_ENVIRONMENT. Must be 'development' or 'prod'."
            exit 1
          fi
      - name: Require read-only Firestore credentials
        env:
          GCP_FIRESTORE_READONLY_CREDENTIALS: ${{ secrets.GCP_FIRESTORE_READONLY_CREDENTIALS }}
        run: |
          if [ -z "$GCP_FIRESTORE_READONLY_CREDENTIALS" ]; then
            echo "::error title=Missing Firestore read-only credentials::Set GCP_FIRESTORE_READONLY_CREDENTIALS in the selected environment before deploying."
            exit 1
          fi

      - name: Checkout current main for source admission
        uses: actions/checkout@v7
        with:
          ref: main
          fetch-depth: 0

      - name: Verify exact admitted main source
        id: admitted_source
        env:
          DEPLOY_SHA: ${{ github.event.inputs.release_sha }}
          GH_TOKEN: ${{ github.token }}
          SKIP_PROOF: ${{ github.event.inputs.skip_eligibility_proof }}
          BREAK_GLASS_CONFIRM: ${{ github.event.inputs.break_glass_confirm }}
          BREAK_GLASS_REASON: ${{ github.event.inputs.break_glass_reason }}
        run: |
          set -euo pipefail
          if [[ ! "$DEPLOY_SHA" =~ ^[0-9a-f]{40}$ || "$DEPLOY_SHA" == "0000000000000000000000000000000000000000" ]]; then
            echo "ERROR: release_sha must be one non-zero, lowercase, full commit SHA."
            exit 1
          fi
          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
          main_sha="$(git rev-parse --verify 'origin/main^{commit}')"
          git cat-file -e "${DEPLOY_SHA}^{commit}"

          # Always enforced, break-glass or not: only merged main code deploys.
          if ! git merge-base --is-ancestor "$DEPLOY_SHA" "$main_sha"; then
            echo "ERROR: release_sha is not an ancestor of origin/main; only merged code may deploy."
            exit 1
          fi

          if [[ "${SKIP_PROOF:-false}" == "true" ]]; then
            if [[ "$BREAK_GLASS_CONFIRM" != "deploy-without-proof" ]]; then
              echo "ERROR: skip_eligibility_proof requires break_glass_confirm=deploy-without-proof." >&2
              exit 1
            fi
            if [[ -z "${BREAK_GLASS_REASON// }" ]]; then
              echo "ERROR: skip_eligibility_proof requires a non-empty break_glass_reason." >&2
              exit 1
            fi
            echo "::warning::Release Eligibility proof skipped for ${DEPLOY_SHA}: ${BREAK_GLASS_REASON}"
            printf 'break_glass=true\n' >> "$GITHUB_OUTPUT"
          else
            proof_path="${RUNNER_TEMP}/release-eligibility-${DEPLOY_SHA}.json"
            gh api -H "Accept: application/vnd.github+json" \
              "repos/${GITHUB_REPOSITORY}/actions/workflows/release-eligibility.yml/runs?event=push&branch=main&status=completed&head_sha=${DEPLOY_SHA}&per_page=100" \
              > "$proof_path"
            python3 .github/scripts/verify_backend_release_admission.py \
              --sha "$DEPLOY_SHA" \
              --repository "$GITHUB_REPOSITORY" \
              --workflow-runs "$proof_path"
            printf 'break_glass=false\n' >> "$GITHUB_OUTPUT"
          fi
          printf 'admitted_sha=%s\n' "$DEPLOY_SHA" >> "$GITHUB_OUTPUT"

      - name: Checkout admitted Firestore source
        uses: actions/checkout@v7
        with:
          ref: ${{ steps.admitted_source.outputs.admitted_sha }}

      - name: Google Auth for read-only Firestore inventory
        uses: 'google-github-actions/auth@v3'
        with:
          credentials_json: ${{ secrets.GCP_FIRESTORE_READONLY_CREDENTIALS }}

      - name: Set up gcloud
        uses: google-github-actions/setup-gcloud@v3

      - name: Verify serving Firestore indexes
        id: firestore_readiness
        env:
          FIRESTORE_PROPOSAL_PATH: ${{ runner.temp }}/firestore-schema-proposal-${{ github.run_id }}-${{ github.run_attempt }}.json
          FIRESTORE_SOURCE_COMMIT: ${{ steps.admitted_source.outputs.admitted_sha }}
        run: |
          python3 backend/scripts/reconcile_firestore_indexes.py \
            --project "${{ vars.RUNTIME_GCP_PROJECT_ID }}" \
            --check-only \
            --proposal-output "$FIRESTORE_PROPOSAL_PATH" \
            --source-commit "$FIRESTORE_SOURCE_COMMIT" \
            --proposal-ttl-seconds 3600

      - name: Validate blocked Firestore schema proposal
        id: validate_firestore_proposal
        if: ${{ failure() && steps.firestore_readiness.outcome == 'failure' }}
        env:
          FIRESTORE_PROPOSAL_PATH: ${{ runner.temp }}/firestore-schema-proposal-${{ github.run_id }}-${{ github.run_attempt }}.json
          FIRESTORE_SOURCE_COMMIT: ${{ steps.admitted_source.outputs.admitted_sha }}
        run: |
          python3 backend/scripts/reconcile_firestore_indexes.py \
            --project "${{ vars.RUNTIME_GCP_PROJECT_ID }}" \
            --validate-proposal "$FIRESTORE_PROPOSAL_PATH" \
            --source-commit "$FIRESTORE_SOURCE_COMMIT" \
            --proposal-ttl-seconds 3600

      - name: Preserve blocked Firestore schema proposal
        if: ${{ failure() && steps.firestore_readiness.outcome == 'failure' && steps.validate_firestore_proposal.outcome == 'success' }}
        uses: actions/upload-artifact@v7
        env:
          FIRESTORE_PROPOSAL_PATH: ${{ runner.temp }}/firestore-schema-proposal-${{ github.run_id }}-${{ github.run_attempt }}.json
        with:
          name: firestore-schema-proposal-${{ github.run_id }}-${{ github.run_attempt }}
          path: ${{ env.FIRESTORE_PROPOSAL_PATH }}
          if-no-files-found: error
          retention-days: 1

  # Kept out of firestore_readiness on purpose: that job is a least-privilege
  # release-proof boundary limited to actions:read/contents:read, so the audit
  # side effect gets its own job rather than widening it.
  record_break_glass:
    needs: firestore_readiness
    if: ${{ needs.firestore_readiness.outputs.break_glass == 'true' }}
    permissions:
      contents: 'read'
      issues: 'write'
    runs-on: ubuntu-latest
    steps:
      - name: Record that the eligibility proof was bypassed
        env:
          GH_TOKEN: ${{ github.token }}
          REPO: ${{ github.repository }}
          DEPLOY_SHA: ${{ needs.firestore_readiness.outputs.admitted_sha }}
          DEPLOY_ENVIRONMENT: ${{ github.event.inputs.environment }}
          BREAK_GLASS_REASON: ${{ github.event.inputs.break_glass_reason }}
        run: |
          set -euo pipefail
          gh issue create --repo "$REPO" \
            --title "Release Eligibility bypassed for ${DEPLOY_SHA:0:10} (${DEPLOY_ENVIRONMENT})" \
            --label release-gate-failure \
            --body "$(printf '%s\n' \
              "Backend deploy ran without a Release Eligibility proof." \
              "" \
              "- SHA: \`${DEPLOY_SHA}\` (verified ancestor of main)" \
              "- Environment: ${DEPLOY_ENVIRONMENT}" \
              "- Operator: @${GITHUB_ACTOR}" \
              "- Reason: ${BREAK_GLASS_REASON}" \
              "- Run: ${GITHUB_SERVER_URL}/${REPO}/actions/runs/${GITHUB_RUN_ID}" \
              "" \
              "The gate being unusable is the defect. Fix the gate, then close this.")"

  deploy:
    needs: [validate-production-boundary, firestore_readiness]
    if: >-
      github.ref == 'refs/heads/main' &&
      github.event.inputs.mode == 'deploy'
    environment: ${{ github.event.inputs.environment }}
    permissions:
      contents: 'read'
      id-token: 'write'

    runs-on: ubuntu-latest-m
    steps:
      - name: Validate Environment Input
        run: |
          if [[ "${{ github.event.inputs.environment }}" != "development" && "${{ github.event.inputs.environment }}" != "prod" ]]; then
            echo "Invalid environment: ${{ github.event.inputs.environment }}. Must be 'development' or 'prod'."
            exit 1
          fi
          if [[ "${{ github.event.inputs.deploy_targets }}" != "all" && "${{ github.event.inputs.deploy_targets }}" != "cloud-run-only" ]]; then
            echo "Invalid deploy_targets: ${{ github.event.inputs.deploy_targets }}. Must be 'all' or 'cloud-run-only'."
            exit 1
          fi
          if [[ "${{ github.event.inputs.deploy_gateway }}" == "true" && "${{ github.event.inputs.environment }}" == "prod" ]]; then
            echo "environment=prod, deploy_gateway=true is unsupported; use the standalone manual LLM gateway workflow." >&2
            exit 1
          fi
          if [[ "${{ github.event.inputs.deploy_gateway }}" == "true" && "${{ github.event.inputs.deploy_targets }}" != "all" ]]; then
            echo "deploy_gateway=true requires deploy_targets=all." >&2
            exit 1
          fi

      # To workaround "no space left on device" issue of GitHub-hosted runner
      - name: Delete huge unnecessary tools folder
        run: rm -rf /opt/hostedtoolcache

      - name: Checkout workflow-owned deploy-control source
        uses: actions/checkout@v7
        with:
          # The workflow owns deployment-control behavior. Pin this source to
          # the immutable workflow revision before the admitted runtime source
          # replaces the normal workspace.
          ref: ${{ github.sha }}
          path: .workflow-source

      - name: Stage immutable workflow validation source and deploy-control scripts
        run: |
          set -euo pipefail
          workflow_source="$RUNNER_TEMP/backend-deploy-workflow-source"
          control_scripts="$RUNNER_TEMP/backend-deploy-control-scripts"
          rm -rf "$workflow_source"
          rm -rf "$control_scripts"
          mkdir -p "$workflow_source"
          cp -a .workflow-source/.github "$workflow_source/.github"
          cp -a .workflow-source/backend/scripts "$control_scripts"
          rm -rf .workflow-source

      - name: Checkout admitted runtime source
        uses: actions/checkout@v7
        with:
          ref: ${{ needs.firestore_readiness.outputs.admitted_sha }}

      - name: Install immutable workflow validation source and deploy-control scripts
        run: |
          set -euo pipefail
          workflow_root="$GITHUB_WORKSPACE/.deploy-workflow-source"
          control_scripts="$GITHUB_WORKSPACE/.deploy-control/scripts"
          rm -rf "$workflow_root"
          rm -rf "$GITHUB_WORKSPACE/.deploy-control"
          mkdir -p "$workflow_root"
          mkdir -p "$(dirname "$control_scripts")"
          cp -a "$RUNNER_TEMP/backend-deploy-workflow-source/.github" "$workflow_root/.github"
          cp -a "$RUNNER_TEMP/backend-deploy-control-scripts" "$control_scripts"
          rm -rf "$RUNNER_TEMP/backend-deploy-workflow-source"
          rm -rf "$RUNNER_TEMP/backend-deploy-control-scripts"
          printf 'DEPLOY_CONTROL_SCRIPTS=%s\n' "$control_scripts" >> "$GITHUB_ENV"
          printf 'DEPLOY_WORKFLOW_ROOT=%s\n' "$workflow_root" >> "$GITHUB_ENV"

      - name: Google Auth
        id: auth
        uses: 'google-github-actions/auth@v3'
        with:
          credentials_json: ${{ secrets.GCP_CREDENTIALS }}

      - name: Set up gcloud
        uses: google-github-actions/setup-gcloud@v3

      - name: Verify serving sync ledger fence mode before deploy
        env:
          SYNC_LEDGER_FENCE_MODE: ${{ vars.SYNC_LEDGER_FENCE_MODE || 'legacy' }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify_sync_ledger_fence_transition.py" \
            --project=${{ vars.GCP_PROJECT_ID }} \
            --region=${{ env.REGION }} \
            --desired-mode="$SYNC_LEDGER_FENCE_MODE"

      - name: Login to GCR
        run: gcloud auth configure-docker

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Compute short SHA
        id: image-tag
        run: |
          SHORT_SHA="$(git rev-parse --short=7 HEAD)"
          echo "short_sha=${SHORT_SHA}" >> "$GITHUB_OUTPUT"
          echo "revision_suffix=${SHORT_SHA}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"

      - name: Install Python deps for deploy scripts
        run: python3 -m pip install -q pyyaml

      - name: Resolve production account-deletion task target
        if: ${{ vars.ENV == 'prod' }}
        id: account-deletion-target
        run: |
          set -euo pipefail
          SYNC_SERVICE_URL="$(
            gcloud run services describe "${{ env.SERVICE }}-sync" \
              --region="${{ env.REGION }}" \
              --project="${{ vars.GCP_PROJECT_ID }}" \
              --format='value(status.url)'
          )"
          SYNC_TASKS_INVOKER_SA="$(
            gcloud run services describe "${{ env.SERVICE }}-sync" \
              --region="${{ env.REGION }}" \
              --project="${{ vars.GCP_PROJECT_ID }}" \
              --format=json \
              | jq -r '.spec.template.spec.containers[0].env[]? | select(.name == "SYNC_TASKS_INVOKER_SA") | .value'
          )"
          test -n "$SYNC_SERVICE_URL"
          test -n "$SYNC_TASKS_INVOKER_SA"
          {
            echo "account_deletion_handler_url=${SYNC_SERVICE_URL}/v1/users/account-deletion-wipes/run"
            echo "listen_finalization_tasks_handler_url=${SYNC_SERVICE_URL}/v1/conversation-finalization-jobs/run"
            echo "listen_finalization_tasks_invoker_sa=${SYNC_TASKS_INVOKER_SA}"
            echo "sync_tasks_handler_url=${SYNC_SERVICE_URL}/v2/sync-jobs/run"
            echo "sync_tasks_invoker_sa=${SYNC_TASKS_INVOKER_SA}"
          } >> "$GITHUB_OUTPUT"

      - name: Determine whether this deploy requests gateway-first serving
        id: gateway-intent
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify-llm-gateway-serving.py" \
            --environment="${{ vars.ENV }}" \
            --project="${{ vars.GCP_PROJECT_ID }}" \
            --region="${{ env.REGION }}" \
            --listener-values="backend/charts/backend-listen/${{ vars.ENV }}_omi_backend_listen_values.yaml" \
            --intent-only >> "$GITHUB_OUTPUT"

      - name: Get GKE credentials for gateway serving gate
        if: ${{ github.event.inputs.deploy_targets == 'all' || steps.gateway-intent.outputs.enabled == 'true' }}
        uses: google-github-actions/get-gke-credentials@v3
        with:
          cluster_name: ${{ vars.GKE_CLUSTER }}
          location: ${{ env.REGION }}
          project_id: ${{ vars.GCP_PROJECT_ID }}

      - name: Verify LLM gateway control plane before promotion
        id: gateway-serving
        if: ${{ github.event.inputs.deploy_gateway != 'true' && steps.gateway-intent.outputs.enabled == 'true' }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify-llm-gateway-serving.py" \
            --environment="${{ vars.ENV }}" \
            --project="${{ vars.GCP_PROJECT_ID }}" \
            --region="${{ env.REGION }}" \
            --github-output "$GITHUB_OUTPUT"

      - name: Preflight Cloud Run deploy
        run: |
          PREFLIGHT_ARGS=(
            --env ${{ vars.ENV }}
            --project ${{ vars.GCP_PROJECT_ID }}
            --region ${{ env.REGION }}
            --check-secrets
            --check-traffic
          )
          if [[ "${{ github.event.inputs.environment }}" == "prod" || "${{ github.event.inputs.environment }}" == "development" ]]; then
            PREFLIGHT_ARGS+=(--repair-traffic)
          fi
          python3 "$DEPLOY_CONTROL_SCRIPTS/preflight-cloud-run-deploy.py" "${PREFLIGHT_ARGS[@]}"

      - name: Validate backend runtime env before deploy
        env:
          SYNC_LEDGER_FENCE_MODE: ${{ vars.SYNC_LEDGER_FENCE_MODE || 'legacy' }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/validate-backend-runtime-env.py" --env ${{ vars.ENV }} --check-workflows --workflow-root "$DEPLOY_WORKFLOW_ROOT" --check-rendered-cloud-run

      - name: Build runtime image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: ./backend/Dockerfile
          push: false
          load: true
          tags: |
            gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:latest
            gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}
          cache-from: type=registry,ref=gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:buildcache
          cache-to: type=registry,ref=gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:buildcache,mode=max

      - name: Verify built runtime image before publish
        run: |
          image=gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}
          python3 "$DEPLOY_CONTROL_SCRIPTS/runtime_image_contracts.py" smoke --dockerfile backend/Dockerfile --image "$image"

      - name: Push verified runtime image
        run: |
          docker push gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:latest
          docker push gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}

      # Development can compose the gateway binary with a full backend deploy.
      # Production remains Cloud Run-only; use gcp_llm_gateway.yml for its
      # separate manual gateway deployment. This helm release changes no caller
      # traffic flags, and the source-controlled caller mode still has to pass
      # the serving and VPC gates below before a Cloud Run revision is created.
      - name: Install Helm for combined LLM Gateway deployment
        if: ${{ github.event.inputs.deploy_gateway == 'true' }}
        uses: azure/setup-helm@v5

      - name: Build, smoke, and push combined LLM Gateway image
        if: ${{ github.event.inputs.deploy_gateway == 'true' }}
        run: |
          gateway_image="gcr.io/${{ vars.GCP_PROJECT_ID }}/llm-gateway:${{ steps.image-tag.outputs.short_sha }}"
          docker build -t "$gateway_image" -f backend/Dockerfile .
          python3 "$DEPLOY_CONTROL_SCRIPTS/runtime_image_contracts.py" smoke \
            --dockerfile backend/Dockerfile \
            --image "$gateway_image"
          docker push "$gateway_image"

      - name: Deploy LLM Gateway with backend stack
        if: ${{ github.event.inputs.deploy_gateway == 'true' }}
        env:
          LLM_GATEWAY_GSA: ${{ vars.LLM_GATEWAY_GSA }}
          ENVIRONMENT: ${{ vars.ENV }}
          GCP_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
          GKE_CLUSTER: ${{ vars.GKE_CLUSTER }}
          REGION: ${{ env.REGION }}
        run: |
          test -n "$LLM_GATEWAY_GSA"
          python3 "$DEPLOY_CONTROL_SCRIPTS/validate-llm-gateway-env.py" \
            backend/charts/backend-listen/${{ vars.ENV }}_omi_backend_listen_values.yaml \
            backend/charts/llm-gateway/${{ vars.ENV }}_omi_llm_gateway_values.yaml
          IMAGE_TAG="${{ steps.image-tag.outputs.short_sha }}" "$DEPLOY_CONTROL_SCRIPTS/deploy-llm-gateway.sh"

      - name: Verify combined LLM gateway serving data plane
        id: combined-gateway-serving
        if: ${{ github.event.inputs.deploy_gateway == 'true' && steps.gateway-intent.outputs.enabled == 'true' }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify-llm-gateway-serving.py" \
            --environment="${{ vars.ENV }}" \
            --project="${{ vars.GCP_PROJECT_ID }}" \
            --region="${{ env.REGION }}" \
            --github-output "$GITHUB_OUTPUT"

      - name: Probe LLM gateway from the Cloud Run VPC before promotion
        if: ${{ steps.gateway-intent.outputs.enabled == 'true' }}
        run: |
          bash "$DEPLOY_CONTROL_SCRIPTS/probe-llm-gateway-from-cloud-run.sh" \
            --project "${{ vars.GCP_PROJECT_ID }}" \
            --region "${{ env.REGION }}" \
            --image "gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}" \
            --gateway-url "${{ steps.combined-gateway-serving.outputs.gateway_url || steps.gateway-serving.outputs.gateway_url }}" \
            --network "${{ vars.CLOUD_RUN_VPC_NETWORK }}" \
            --subnet "${{ vars.CLOUD_RUN_VPC_SUBNET }}" \
            --vpc-egress private-ranges-only \
            --lane omi:auto:public-shared-conversation-chat \
            --name-suffix "${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"

      - name: Reject an inert gateway endpoint when source-controlled gateway mode is requested
        if: ${{ steps.gateway-intent.outputs.enabled == 'true' }}
        env:
          GATEWAY_URL: ${{ steps.combined-gateway-serving.outputs.gateway_url || steps.gateway-serving.outputs.gateway_url }}
        run: |
          set -euo pipefail
          if [[ -z "$GATEWAY_URL" || "$GATEWAY_URL" == "http://127.0.0.1:9" ]]; then
            echo "Gateway mode requires a verified non-sentinel endpoint." >&2
            exit 1
          fi

      # The endpoint is rendered only after the deployment gate derived it
      # from the provisioned ingress address. Direct mode gets the inert
      # sentinel from the manifest and does not require a gateway dependency.
      - name: Render backend runtime env
        id: runtime-env
        env:
          ACCOUNT_DELETION_HANDLER_URL: ${{ steps.account-deletion-target.outputs.account_deletion_handler_url }}
          LISTEN_FINALIZATION_TASKS_HANDLER_URL: ${{ steps.account-deletion-target.outputs.listen_finalization_tasks_handler_url }}
          LISTEN_FINALIZATION_TASKS_INVOKER_SA: ${{ steps.account-deletion-target.outputs.listen_finalization_tasks_invoker_sa }}
          CLOUD_RUN_VPC_NETWORK: ${{ vars.CLOUD_RUN_VPC_NETWORK }}
          CLOUD_RUN_VPC_SUBNET: ${{ vars.CLOUD_RUN_VPC_SUBNET }}
          GOOGLE_CLIENT_ID: ${{ vars.GOOGLE_CLIENT_ID }}
          MCP_OAUTH_CLAUDE_CLIENT_ID: ${{ vars.MCP_OAUTH_CLAUDE_CLIENT_ID }}
          MCP_OAUTH_CLAUDE_CLIENT_NAME: ${{ vars.MCP_OAUTH_CLAUDE_CLIENT_NAME }}
          MCP_OAUTH_CLAUDE_REDIRECT_URIS: ${{ vars.MCP_OAUTH_CLAUDE_REDIRECT_URIS }}
          OMI_LLM_GATEWAY_URL: ${{ steps.combined-gateway-serving.outputs.gateway_url || steps.gateway-serving.outputs.gateway_url || 'http://127.0.0.1:9' }}
          PUBLIC_SHARED_CONVERSATION_CHAT_FRONTEND_AUDIENCE: ${{ vars.PUBLIC_SHARED_CONVERSATION_CHAT_FRONTEND_AUDIENCE }}
          PUBLIC_SHARED_CONVERSATION_CHAT_FRONTEND_INVOKER_SA: ${{ vars.PUBLIC_SHARED_CONVERSATION_CHAT_FRONTEND_INVOKER_SA }}
          SYNC_LEDGER_FENCE_MODE: ${{ vars.SYNC_LEDGER_FENCE_MODE || 'legacy' }}
          SYNC_TASKS_HANDLER_URL: ${{ steps.account-deletion-target.outputs.sync_tasks_handler_url }}
          SYNC_TASKS_INVOKER_SA: ${{ steps.account-deletion-target.outputs.sync_tasks_invoker_sa }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/render_backend_runtime_env.py" --env ${{ vars.ENV }} >> "$GITHUB_OUTPUT"

      # Strips Secret Manager bindings left on services for settings the manifest
      # now declares as public literals; gcloud cannot flip a binding's type in
      # place. No-ops once a service carries no legacy binding.
      - name: Migrate legacy public Cloud Run bindings
        run: >-
          python3 "$DEPLOY_CONTROL_SCRIPTS/preflight-cloud-run-deploy.py"
          --env ${{ vars.ENV }}
          --project="${{ vars.GCP_PROJECT_ID }}"
          --region="${{ env.REGION }}"
          --migrate-legacy-public-binding backend
          --migrate-legacy-public-binding backend-sync
          --migrate-legacy-public-binding backend-sync-backfill
          --migrate-legacy-public-binding backend-integration

      - name: Deploy ${{ env.SERVICE }} to Cloud Run
        id: deploy-backend
        uses: google-github-actions/deploy-cloudrun@v3
        with:
          service: ${{ env.SERVICE }}
          region: ${{ env.REGION }}
          project_id: ${{ vars.GCP_PROJECT_ID }}
          image: gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}
          no_traffic: true
          flags: >-
            --revision-suffix=${{ steps.image-tag.outputs.revision_suffix }}
            ${{ github.event.inputs.environment == 'development' && format('--tag={0}', env.TRANSCRIPTION_CANDIDATE_TAG) || '' }}
            ${{ steps.runtime-env.outputs.cloud_run_flags }}
          env_vars: ${{ steps.runtime-env.outputs.backend_env_vars }}
          secrets: ${{ steps.runtime-env.outputs.backend_secrets }}

      - name: Capture ${{ env.SERVICE }} revision
        id: capture-backend-revision
        run: |
          echo "revision=backend-${{ steps.image-tag.outputs.revision_suffix }}" >> "$GITHUB_OUTPUT"

      - name: Deploy sync-backfill worker
        id: sync-backfill
        uses: ./.github/actions/sync-backfill-lifecycle
        with:
          mode: worker
          project_id: ${{ vars.GCP_PROJECT_ID }}
          region: ${{ env.REGION }}
          service: ${{ env.SERVICE }}
          image: gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}
          revision_suffix: ${{ steps.image-tag.outputs.revision_suffix }}
          cloud_run_flags: ${{ steps.runtime-env.outputs.cloud_run_flags }}
          backfill_env_vars: ${{ steps.runtime-env.outputs.backend_sync_backfill_env_vars }}
          backfill_secrets: ${{ steps.runtime-env.outputs.backend_sync_backfill_secrets }}

      - name: Deploy ${{ env.SERVICE }}-sync to Cloud Run
        id: deploy-backend-sync
        uses: google-github-actions/deploy-cloudrun@v3
        with:
          service: ${{ env.SERVICE }}-sync
          region: ${{ env.REGION }}
          project_id: ${{ vars.GCP_PROJECT_ID }}
          image: gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}
          no_traffic: true
          flags: >-
            --revision-suffix=${{ steps.image-tag.outputs.revision_suffix }}
            --remove-env-vars=HOSTED_PUSHER_API_URL
            ${{ steps.runtime-env.outputs.cloud_run_flags }}
          env_vars: |-
            ${{ steps.runtime-env.outputs.backend_sync_env_vars }}
            ${{ steps.sync-backfill.outputs.sync_backfill_env_vars }}
          secrets: ${{ steps.runtime-env.outputs.backend_sync_secrets }}

      - name: Capture ${{ env.SERVICE }}-sync revision
        id: capture-backend-sync-revision
        run: |
          echo "revision=backend-sync-${{ steps.image-tag.outputs.revision_suffix }}" >> "$GITHUB_OUTPUT"

      - name: Provision sync-backfill platform
        if: ${{ github.event.inputs.deploy_targets == 'all' }}
        uses: ./.github/actions/sync-backfill-lifecycle
        with:
          mode: platform
          project_id: ${{ vars.GCP_PROJECT_ID }}
          region: ${{ env.REGION }}
          service: ${{ env.SERVICE }}
          provision_sync_ledger_ttl: 'true'
          provision_budget_alerts: ${{ github.event.inputs.environment == 'prod' && 'true' || 'false' }}
          alert_notification_channels: ${{ vars.SYNC_BACKFILL_ALERT_NOTIFICATION_CHANNELS }}

      - name: Configure production conversation-finalization Cloud Tasks queue
        if: ${{ vars.ENV == 'prod' && github.event.inputs.deploy_targets == 'all' }}
        env:
          TASKS_INVOKER_SA: ${{ steps.account-deletion-target.outputs.listen_finalization_tasks_invoker_sa }}
        run: |
          set -euo pipefail
          test -n "$TASKS_INVOKER_SA"
          gcloud run services add-iam-policy-binding "${{ env.SERVICE }}-sync" \
            --region="${{ env.REGION }}" \
            --project="${{ vars.GCP_PROJECT_ID }}" \
            --member="serviceAccount:${TASKS_INVOKER_SA}" \
            --role=roles/run.invoker \
            --quiet
          if gcloud tasks queues describe conversation-finalization \
            --location="${{ env.REGION }}" \
            --project="${{ vars.GCP_PROJECT_ID }}" >/dev/null 2>&1; then
            gcloud tasks queues update conversation-finalization \
              --location="${{ env.REGION }}" \
              --project="${{ vars.GCP_PROJECT_ID }}" \
              --max-attempts=5 \
              --max-concurrent-dispatches=4
          else
            gcloud tasks queues create conversation-finalization \
              --location="${{ env.REGION }}" \
              --project="${{ vars.GCP_PROJECT_ID }}" \
              --max-attempts=5 \
              --max-concurrent-dispatches=4
          fi

      - name: Deploy ${{ env.SERVICE }}-integration to Cloud Run
        id: deploy-backend-integration
        uses: google-github-actions/deploy-cloudrun@v3
        with:
          service: ${{ env.SERVICE }}-integration
          region: ${{ env.REGION }}
          project_id: ${{ vars.GCP_PROJECT_ID }}
          image: gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }}:${{ steps.image-tag.outputs.short_sha }}
          no_traffic: true
          flags: >-
            --revision-suffix=${{ steps.image-tag.outputs.revision_suffix }}
            --remove-env-vars=HOSTED_PUSHER_API_URL
            ${{ steps.runtime-env.outputs.cloud_run_flags }}
          env_vars: ${{ steps.runtime-env.outputs.backend_integration_env_vars }}
          secrets: ${{ steps.runtime-env.outputs.backend_integration_secrets }}

      - name: Capture ${{ env.SERVICE }}-integration revision
        id: capture-backend-integration-revision
        run: |
          echo "revision=backend-integration-${{ steps.image-tag.outputs.revision_suffix }}" >> "$GITHUB_OUTPUT"

      - name: Wait for Cloud Run revisions to become ready
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/preflight-cloud-run-deploy.py" \
            --env ${{ vars.ENV }} \
            --project ${{ vars.GCP_PROJECT_ID }} \
            --region ${{ env.REGION }} \
            --wait-revision-ready backend=${{ steps.capture-backend-revision.outputs.revision }} \
            --wait-revision-ready backend-sync=${{ steps.capture-backend-sync-revision.outputs.revision }} \
            --wait-revision-ready backend-sync-backfill=${{ steps.sync-backfill.outputs.revision }} \
            --wait-revision-ready backend-integration=${{ steps.capture-backend-integration-revision.outputs.revision }}

      - name: Validate backend runtime env after deploy
        env:
          SYNC_LEDGER_FENCE_MODE: ${{ vars.SYNC_LEDGER_FENCE_MODE || 'legacy' }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/validate-backend-runtime-env.py" --env ${{ vars.ENV }} --check-workflows --workflow-root "$DEPLOY_WORKFLOW_ROOT" --check-live-cloud-run

      # Development probes the no-traffic tagged revision directly from the
      # runner. Production has no tagged candidate URL or private probe job.
      - name: Resolve transcription candidate URL
        id: transcription-candidate
        if: ${{ github.event.inputs.environment == 'development' }}
        run: |
          candidate_url="$(python3 "$DEPLOY_CONTROL_SCRIPTS/resolve_cloud_run_tagged_url.py" \
            --project=${{ vars.GCP_PROJECT_ID }} \
            --region=${{ env.REGION }} \
            --service=${{ env.SERVICE }} \
            --revision=${{ steps.capture-backend-revision.outputs.revision }} \
            --tag="$TRANSCRIPTION_CANDIDATE_TAG")"
          printf 'url=%s\n' "$candidate_url" >> "$GITHUB_OUTPUT"

      - name: Gate backend candidate on known audio
        if: ${{ github.event.inputs.environment == 'development' }}
        uses: ./.github/actions/transcription-release-candidate-probe
        with:
          candidate_api_url: ${{ steps.transcription-candidate.outputs.url }}
          project_id: ${{ vars.GCP_PROJECT_ID }}
          firebase_auth_project_id: based-hardware

      # This Cloud Run-only acceptance boundary runs before any traffic shift.
      - name: Accept no-traffic Cloud Run candidate
        id: verify-cloud-run-candidate
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify_backend_release_vector.py" \
            --candidate \
            --cloud-run-only \
            --commit-sha "${{ needs.firestore_readiness.outputs.admitted_sha }}" \
            --short-sha "${{ steps.image-tag.outputs.short_sha }}" \
            --deploy-run-id "${{ github.run_id }}" \
            --deploy-run-attempt "${{ github.run_attempt }}" \
            --project "${{ vars.GCP_PROJECT_ID }}" \
            --region "${{ env.REGION }}" \
            --environment "${{ vars.ENV }}" \
            --evidence-path artifacts/backend-cloud-run-candidate-release-vector.json

      - name: Remove passed transcription candidate tag
        if: ${{ success() && github.event.inputs.environment == 'development' }}
        run: |
          gcloud run services update-traffic ${{ env.SERVICE }} \
            --project=${{ vars.GCP_PROJECT_ID }} \
            --region=${{ env.REGION }} \
            --remove-tags="$TRANSCRIPTION_CANDIDATE_TAG" \
            --quiet

      - name: Remove failed transcription candidate tag
        # Tag is created at deploy-backend; clean it up on any later failure,
        # not only after the candidate URL resolution step succeeds.
        if: ${{ failure() && steps.deploy-backend.outcome == 'success' && github.event.inputs.environment == 'development' }}
        run: |
          gcloud run services update-traffic ${{ env.SERVICE }} \
            --project=${{ vars.GCP_PROJECT_ID }} \
            --region=${{ env.REGION }} \
            --remove-tags="$TRANSCRIPTION_CANDIDATE_TAG" \
            --quiet

      - name: Install Helm
        if: ${{ github.event.inputs.deploy_targets == 'all' }}
        uses: azure/setup-helm@v5

      - name: Apply non-secret backend runtime config
        if: ${{ github.event.inputs.deploy_targets == 'all' }}
        env:
          ACCOUNT_DELETION_HANDLER_URL: ${{ steps.account-deletion-target.outputs.account_deletion_handler_url }}
          ENVIRONMENT: ${{ vars.ENV }}
          CONVERSATION_SUMMARIZED_APP_IDS: ${{ vars.CONVERSATION_SUMMARIZED_APP_IDS }}
          GOOGLE_CLIENT_ID: ${{ vars.GOOGLE_CLIENT_ID }}
          MCP_AUTHORIZATION_SERVER_URL: ${{ vars.MCP_AUTHORIZATION_SERVER_URL }}
          MCP_OAUTH_CHATGPT_CLIENT_ID: ${{ vars.MCP_OAUTH_CHATGPT_CLIENT_ID }}
          MCP_OAUTH_CHATGPT_REDIRECT_URIS: ${{ vars.MCP_OAUTH_CHATGPT_REDIRECT_URIS }}
          MCP_OAUTH_CLAUDE_CLIENT_ID: ${{ vars.MCP_OAUTH_CLAUDE_CLIENT_ID }}
          MCP_OAUTH_CLAUDE_CLIENT_NAME: ${{ vars.MCP_OAUTH_CLAUDE_CLIENT_NAME }}
          MCP_OAUTH_CLAUDE_REDIRECT_URIS: ${{ vars.MCP_OAUTH_CLAUDE_REDIRECT_URIS }}
          MCP_OAUTH_PUBLIC_CLIENT_ID: ${{ vars.MCP_OAUTH_PUBLIC_CLIENT_ID }}
          MCP_OAUTH_PUBLIC_REDIRECT_URIS: ${{ vars.MCP_OAUTH_PUBLIC_REDIRECT_URIS }}
          MCP_RESOURCE_URL: ${{ vars.MCP_RESOURCE_URL }}
          RAPID_API_HOST: ${{ vars.RAPID_API_HOST }}
          REDIS_DB_HOST: ${{ vars.REDIS_DB_HOST }}
          STT_PRERECORDED_MODEL: modulate-velma-2,parakeet
          STT_SERVICE_MODELS: modulate-velma-2,parakeet
          SYNC_TASKS_HANDLER_URL: ${{ steps.account-deletion-target.outputs.sync_tasks_handler_url }}
          SYNC_TASKS_INVOKER_SA: ${{ steps.account-deletion-target.outputs.sync_tasks_invoker_sa }}
          TYPESENSE_HOST: ${{ vars.TYPESENSE_HOST }}
          TWILIO_ACCOUNT_SID: ${{ vars.TWILIO_ACCOUNT_SID }}
          TWILIO_API_KEY_SID: ${{ vars.TWILIO_API_KEY_SID }}
          TWILIO_TWIML_APP_SID: ${{ vars.TWILIO_TWIML_APP_SID }}
          X_OAUTH_CLIENT_ID: ${{ vars.X_OAUTH_CLIENT_ID }}
          X_OAUTH_REDIRECT_URI: ${{ vars.X_OAUTH_REDIRECT_URI }}
        run: bash "$DEPLOY_CONTROL_SCRIPTS/deploy-backend-config.sh"

      - name: Deploy backend-secrets to GKE using Helm
        if: ${{ github.event.inputs.deploy_targets == 'all' }}
        env:
          ENVIRONMENT: ${{ vars.ENV }}
          GCP_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
          GKE_CLUSTER: ${{ vars.GKE_CLUSTER }}
          REGION: ${{ env.REGION }}
        run: bash "$DEPLOY_CONTROL_SCRIPTS/deploy-backend-secrets.sh"

      - name: Deploy ${{ env.SERVICE }}-listen to GKE using Helm
        if: ${{ github.event.inputs.deploy_targets == 'all' }}
        run: |
          helm -n ${{ vars.ENV }}-omi-backend upgrade --install ${{ vars.ENV }}-omi-backend-listen ./backend/charts/backend-listen \
            -f ./backend/charts/backend-listen/${{ vars.ENV }}_omi_backend_listen_values.yaml \
            --set image.repository=gcr.io/${{ vars.GCP_PROJECT_ID }}/${{ env.SERVICE }} \
            --set gcpProjectId=${{ vars.GCP_PROJECT_ID }} \
            --set runtimeGcpProjectId=${{ vars.RUNTIME_GCP_PROJECT_ID }} \
            --set-string image.tag=${{ steps.image-tag.outputs.short_sha }}
          # Bounds a healthy-but-slow rollout, not a stuck one: backend-listen runs
          # 12-60 HPA replicas rolled 3 at a time (maxSurge=2, maxUnavailable=1) and
          # its startupProbe alone permits 300s per pod, so a full roll routinely
          # exceeds 300s and node scale-up adds more. A genuinely stalled rollout
          # still fails fast on the deployment's 600s progressDeadlineSeconds, which
          # kubectl reports as ProgressDeadlineExceeded regardless of this value.
          if ! kubectl -n ${{ vars.ENV }}-omi-backend rollout status deploy/${{ vars.ENV }}-omi-backend-listen --timeout=1800s; then
            python3 "$DEPLOY_CONTROL_SCRIPTS/deploy_status_report.py" --env ${{ vars.ENV }} --include-gke --gke-service backend-listen || true
            exit 1
          fi
          python3 "$DEPLOY_CONTROL_SCRIPTS/deploy_status_report.py" --env ${{ vars.ENV }} --include-gke --gke-service backend-listen

      - name: Verify exact candidate composition
        if: ${{ github.event.inputs.deploy_targets == 'all' }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify_backend_release_vector.py" \
            --candidate \
            --commit-sha "${{ needs.firestore_readiness.outputs.admitted_sha }}" \
            --short-sha "${{ steps.image-tag.outputs.short_sha }}" \
            --deploy-run-id "${{ github.run_id }}" \
            --deploy-run-attempt "${{ github.run_attempt }}" \
            --project "${{ vars.GCP_PROJECT_ID }}" \
            --region "${{ env.REGION }}" \
            --environment "${{ vars.ENV }}" \
            --evidence-path artifacts/backend-deployment-composition.json

      - name: Capture Cloud Run pre-promotion traffic snapshot
        id: cloud-run-traffic-snapshot
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/cloud_run_traffic_snapshot.py" capture \
            --project "${{ vars.GCP_PROJECT_ID }}" \
            --region "${{ env.REGION }}" \
            --service backend \
            --service backend-sync \
            --service backend-sync-backfill \
            --service backend-integration \
            --output artifacts/backend-cloud-run-pre-promotion-traffic-snapshot.json

      - name: Verify validated revisions are still current
        run: |
          test "$(gcloud run services describe backend --region=${{ env.REGION }} --format='value(status.latestCreatedRevisionName)')" = "${{ steps.capture-backend-revision.outputs.revision }}"
          test "$(gcloud run services describe backend-sync --region=${{ env.REGION }} --format='value(status.latestCreatedRevisionName)')" = "${{ steps.capture-backend-sync-revision.outputs.revision }}"
          test "$(gcloud run services describe backend-sync-backfill --region=${{ env.REGION }} --format='value(status.latestCreatedRevisionName)')" = "${{ steps.sync-backfill.outputs.revision }}"
          test "$(gcloud run services describe backend-integration --region=${{ env.REGION }} --format='value(status.latestCreatedRevisionName)')" = "${{ steps.capture-backend-integration-revision.outputs.revision }}"

      - name: Shift Cloud Run traffic to validated revisions
        id: shift-cloud-run-traffic
        run: |
          gcloud run services update-traffic backend --project=${{ vars.GCP_PROJECT_ID }} --region=${{ env.REGION }} --to-revisions=${{ steps.capture-backend-revision.outputs.revision }}=100 --quiet
          gcloud run services update-traffic backend-sync --project=${{ vars.GCP_PROJECT_ID }} --region=${{ env.REGION }} --to-revisions=${{ steps.capture-backend-sync-revision.outputs.revision }}=100 --quiet
          gcloud run services update-traffic backend-sync-backfill --project=${{ vars.GCP_PROJECT_ID }} --region=${{ env.REGION }} --to-revisions=${{ steps.sync-backfill.outputs.revision }}=100 --quiet
          gcloud run services update-traffic backend-integration --project=${{ vars.GCP_PROJECT_ID }} --region=${{ env.REGION }} --to-revisions=${{ steps.capture-backend-integration-revision.outputs.revision }}=100 --quiet

      # A traffic command can complete after an earlier target has moved. The
      # shared deploy lock prevents competing writers, while this read-only
      # gate prevents a partial apply from being reported as a healthy release.
      - name: Verify serving backend release vector
        id: verify-serving-release-vector
        run: |
          CLOUD_RUN_ONLY=""
          if [[ "${{ github.event.inputs.deploy_targets }}" == "cloud-run-only" ]]; then
            CLOUD_RUN_ONLY="--cloud-run-only"
          fi
          python3 "$DEPLOY_CONTROL_SCRIPTS/verify_backend_release_vector.py" \
            --commit-sha "${{ needs.firestore_readiness.outputs.admitted_sha }}" \
            --short-sha "${{ steps.image-tag.outputs.short_sha }}" \
            --deploy-run-id "${{ github.run_id }}" \
            --deploy-run-attempt "${{ github.run_attempt }}" \
            --project "${{ vars.GCP_PROJECT_ID }}" \
            --region "${{ env.REGION }}" \
            --environment "${{ vars.ENV }}" \
            --evidence-path artifacts/backend-serving-release-vector.json \
            $CLOUD_RUN_ONLY

      - name: Smoke promoted production serving API
        id: smoke-promoted-production-serving-api
        if: ${{ github.event.inputs.environment == 'prod' }}
        env:
          PROBE_SECRET_PROJECT: ${{ vars.GCP_PROJECT_ID }}
          FIREBASE_AUTH_PROJECT_ID: based-hardware
        run: |
          set -euo pipefail
          umask 077
          token_file="$RUNNER_TEMP/firebase-production-serving-token"
          trap 'rm -f "$token_file"' EXIT
          python3 "$DEPLOY_CONTROL_SCRIPTS/firebase_release_probe_token.py" \
            --secret-project "$PROBE_SECRET_PROJECT" \
            --firebase-project "$FIREBASE_AUTH_PROJECT_ID" \
            --token-output "$token_file"
          reservation_status="$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
            --request POST https://api.omi.me/v2/desktop/beta/candidates/reserve \
            --header 'Content-Type: application/json' --data '{"tag":"v0.0.0+1-macos"}')"
          # A schema-valid inert tag reaches the authorization wall without reserving a real candidate.
          test "$reservation_status" = 401
          python3 "$DEPLOY_CONTROL_SCRIPTS/transcription_capability_probe.py" \
            --candidate-api-url https://api.omi.me \
            --bearer-token-file "$token_file" --json-only

      - name: Restore Cloud Run traffic snapshot after failed promotion
        if: ${{ failure() && steps.cloud-run-traffic-snapshot.outcome == 'success' && (steps.shift-cloud-run-traffic.outcome == 'failure' || steps.verify-serving-release-vector.outcome == 'failure' || steps.smoke-promoted-production-serving-api.outcome == 'failure') }}
        run: |
          python3 "$DEPLOY_CONTROL_SCRIPTS/cloud_run_traffic_snapshot.py" restore \
            --snapshot artifacts/backend-cloud-run-pre-promotion-traffic-snapshot.json \
            --evidence-path artifacts/backend-cloud-run-traffic-restore.json

      - name: Smoke What Matters Now datastore query
        if: ${{ github.event.inputs.environment == 'development' }}
        env:
          PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
        run: |
          set -euo pipefail
          ADMIN_KEY="$(gcloud secrets versions access latest --secret=ADMIN_KEY --project="$PROJECT_ID")"
          export ADMIN_KEY
          trap 'unset ADMIN_KEY' EXIT
          python3 "$DEPLOY_CONTROL_SCRIPTS/smoke_what_matters_now.py" --base-url https://api.omi.dev

      - name: Cloud Run deploy status report
        if: always()
        run: |
          set -o pipefail
          if [[ "${{ steps.verify-cloud-run-candidate.outcome }}" != "success" ]]; then
            echo "Cloud Run candidate verification failed before traffic promotion; candidate evidence follows."
            cat artifacts/backend-cloud-run-candidate-release-vector.json || true
            exit 0
          fi
          expected_traffic=()
          if [[ "${{ steps.shift-cloud-run-traffic.outcome }}" == "success" ]]; then
            expected_traffic=(
              --expect-cloud-run-traffic backend=${{ steps.capture-backend-revision.outputs.revision }}
              --expect-cloud-run-traffic backend-sync=${{ steps.capture-backend-sync-revision.outputs.revision }}
              --expect-cloud-run-traffic backend-sync-backfill=${{ steps.sync-backfill.outputs.revision }}
              --expect-cloud-run-traffic backend-integration=${{ steps.capture-backend-integration-revision.outputs.revision }}
            )
          fi
          python3 "$DEPLOY_CONTROL_SCRIPTS/deploy_status_report.py" \
            --env ${{ vars.ENV }} \
            --project ${{ vars.GCP_PROJECT_ID }} \
            --region ${{ env.REGION }} \
            --include-cloud-run \
            --cloud-run-service backend \
            --cloud-run-service backend-sync \
            --cloud-run-service backend-sync-backfill \
            --cloud-run-service backend-integration \
            "${expected_traffic[@]}" \
            | tee /tmp/cloud-run-deploy-status.txt
          if [[ "${{ github.event.inputs.environment }}" == "prod" ]]; then
            {
              echo ""
              echo "### Cloud Run rollout status"
              echo ""
              echo '```text'
              cat /tmp/cloud-run-deploy-status.txt
              echo '```'
            } >> "$GITHUB_STEP_SUMMARY"
          fi

      - name: Upload backend release-vector evidence
        if: ${{ always() }}
        uses: actions/upload-artifact@v7
        with:
          name: backend-deployment-evidence-${{ github.run_id }}-${{ github.run_attempt }}
          path: |
            artifacts/backend-cloud-run-candidate-release-vector.json
            artifacts/backend-deployment-composition.json
            artifacts/backend-cloud-run-pre-promotion-traffic-snapshot.json
            artifacts/backend-serving-release-vector.json
            artifacts/backend-cloud-run-traffic-restore.json
          if-no-files-found: warn

      # If required, use the Cloud Run url output in later steps
      - name: Show Output
        run: echo ${{ steps.deploy-backend.outputs.url }}

      - name: Generate deployment summary
        if: always() && github.event.inputs.environment == 'prod'
        uses: ./.github/actions/deployment-summary
        with:
          environment: ${{ github.event.inputs.environment }}
          release_version: ${{ github.event.inputs.release_version }}
          status: ${{ job.status }}
          service: ${{ env.SERVICE }}

      - name: Notify deployment status on Telegram
        if: always() && github.event.inputs.environment == 'prod'
        uses: ./.github/actions/deployment-notifier
        with:
          environment: ${{ github.event.inputs.environment }}
          release_version: ${{ github.event.inputs.release_version }}
          status: ${{ job.status }}
          telegram_bot_token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
          telegram_chat_id: ${{ secrets.TELEGRAM_CHAT_ID }}