Cloud Deploy — GCP & AWS (backend/worker)

Overview

A backend deploy ships the container the repo already builds, not a re-implementation. The same image runs on Google Cloud Run and on AWS ECS — the deploy workflow only differs in the auth handshake and the deploy command. Read [[ci-cd-pipeline-authoring]] first: it defines the workflow naming/dispatch contract this skill fills in with real cloud steps.

Core principle: One image, one health-checked deploy per environment, authenticated by OIDC — never a hand-rolled server or a committed key.

Pick the target, then copy the boilerplate

1. Decide the cloud (project's existing infra wins) and app type (backend or worker).
2. search_boilerplate_catalog → deploy gcp backend, deploy aws worker, etc. Copy that folder's deploy-stage/preprod/prod.yml into the project's .github/workflows/ as <id>-deploy-<env>.yml.
3. Fill in the repo/environment vars its README lists (project id, region, service name, image repo). Set up the OIDC trust once (WIF pool / IAM role) — the README has the exact steps.

GCP — Cloud Run

• Auth: google-github-actions/auth with workload_identity_provider + service_account (no key JSON).
• Deploy: gcloud run deploy $SERVICE --image $IMAGE --region $REGION (or --source . to build on deploy). Cloud Run gives you the revision URL to smoke-test.
• Worker (no HTTP ingress): deploy as a Cloud Run job (gcloud run jobs deploy ... && gcloud run jobs execute) or a GKE workload — not a public service.

AWS — ECS Express Mode / Fargate

• Auth: aws-actions/configure-aws-credentials with role-to-assume (OIDC), no access keys.
• ECS Express Mode is AWS's recommended default (App Runner stopped accepting new customers on 2026-04-30; existing App Runner services keep working, but don't build new ones there): push the image to ECR, then let Express Mode provision and run the service from it — the simplest path for a single service today.
• ECS Fargate (more control over task definitions, scaling, networking): push to ECR, render the task definition, aws-actions/amazon-ecs-deploy-task-definition with wait-for-service-stability: true.
• Worker: an ECS service with no load balancer / no public subnet.

Migrate before deploy

• Schema migrations run as a pre-deploy step against the target environment's database, gated per environment, before the new image is switched in. A failed migration must fail the workflow before any traffic shift.
• Migrations are forward-only and backward-compatible with the currently-running image (expand/contract) so a rollback of the image doesn't break on the new schema. See [[postgres-migrations]].
• Never point a stage/preprod deploy at the production database. One database per environment; the DB URL comes from that environment's vars/secrets.

Health-check gate & rollback

• End every deploy job with a smoke step: curl the health endpoint (Cloud Run revision URL / ECS service URL / ALB DNS) and fail the job on non-200. A failing smoke step fails the deploy — the release goes failed and the release engineer rolls it back; only finish_release moves a task to released. This workflow's smoke step is a build-time gate, not the release verdict itself.
• Rollback is redeploying the previous image tag/revision — keep deploys immutable-tagged (git SHA), never :latest. Put the rollback command in the task's rollback_plan field (update_board_task) so the release engineer reads it on rollback — that field is posted on the card automatically at deploy time, which a comment is not.

Common Mistakes

• Deploying :latest → no deterministic rollback target. Tag with the commit SHA.
• Running migrations from inside app startup instead of a gated pre-deploy step → half-migrated env on crash-loop.
• Stage deploy sharing the prod database.
• A deploy job that reports success without ever hitting the health endpoint.
• Storing a GCP service-account JSON or AWS access key in secrets instead of using OIDC/WIF.
• Standing up a new App Runner service instead of ECS Express Mode — it still works for existing services, but it is closed to new customers.

Red Flags

• The workflow has no id-token: write permission (OIDC can't work).
• No smoke step, or a smoke step whose failure doesn't fail the job.
• Preprod/prod deploy triggers on push instead of workflow_dispatch (unless the component's delivery profile is genuinely on_merge).