Canary

/canary — Canary Deployment with Smoke Tests

You are deploying code through a canary process: deploy a zero-traffic revision, verify it works, then promote to live traffic. This prevents broken deploys from reaching users.

Ethos

!test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init to vendor .adlc/ETHOS.md

Context

• Current directory: !pwd
• Current branch: !git branch --show-current || echo Not a git repo
• GCP project: !gcloud config get-value project 2>/dev/null || echo "No GCP project configured"
• Active Cloud Run services: !gcloud run services list --format="table(SERVICE,REGION,URL)" 2>/dev/null || echo "gcloud not configured"

Input

Target: $ARGUMENTS

Prerequisites

1. gcloud CLI must be authenticated and configured with the correct project
2. The service must already exist on Cloud Run (this skill deploys revisions, not new services)
3. A Docker image must be available (either build locally or use the latest from Artifact Registry)

Service Resolution

Service configuration lives in .adlc/config.yml in the primary repo under a services: block, keyed by repo id. This is the single source of truth — no service names, regions, or image paths should be hardcoded in this skill.

Expected config shape (primary repo .adlc/config.yml):

repos:
  api:
    path: ../api
  web:
    path: ../web

services:
  api:
    cloud_run_service: api
    region: us-central1
    image_path: us-central1-docker.pkg.dev/<gcp-project>/api/api
  web:
    cloud_run_service: web
    region: us-central1
    image_path: us-central1-docker.pkg.dev/<gcp-project>/web/web

Resolution order:

1. If $ARGUMENTS is a repo id defined under repos: in the primary's config, look up services[<repo-id>] and use that. If the repo id has no services: entry, stop and ask the user to add one.
2. If $ARGUMENTS is a Cloud Run service name already (e.g., the user passed api and it matches services.*.cloud_run_service), use that entry.
3. If no argument: detect which repo the current cwd is inside by walking up to find a git root and matching it against repos[*].path (resolve each to an absolute path first). Then look up its service.
4. If the project has no .adlc/config.yml (single-repo legacy setup) AND the current repo has a top-level Dockerfile and a single Cloud Run service name that matches the repo basename, fall back to auto-detection: service name = repo basename, region = us-central1, image path = $(gcloud config get-value project)/<service>. Surface this fallback in the logs so the user knows it's being inferred.
5. If none of the above resolves, stop with a clear error: "Could not determine Cloud Run service. Add a services: block to .adlc/config.yml or pass the service name as an argument."

Operating worktree: if the resolved repo has a feature-branch worktree (e.g., .worktrees/REQ-xxx) that matches the current /proceed pipeline, build from inside that worktree. Otherwise build from the repo's main checkout. The caller can also pass the worktree path explicitly.

Note (post-REQ-380, REQ-381): /canary is no longer auto-invoked from /proceed (REQ-380) or /bugfix (REQ-381). Operators run it manually when a production canary is needed.

Instructions

Step 1: Build and Push Image

1. Determine the image tag: use the current git SHA (git rev-parse --short HEAD)
2. Build the Docker image:

   docker build -t <IMAGE_PATH>:canary-<SHA> ./<subdir if needed>

3. Push to Artifact Registry:

   docker push <IMAGE_PATH>:canary-<SHA>

If the user says "use latest" or the image was already built by CI, skip the build and use the :latest tag from Artifact Registry.

Step 2: Deploy Canary Revision (Zero Traffic)

Deploy a new revision that receives NO traffic:

gcloud run deploy <SERVICE_NAME> \
  --image=<IMAGE_PATH>:canary-<SHA> \
  --region=us-central1 \
  --no-traffic \
  --tag=canary \
  --format="json"

This creates a tagged revision accessible at https://canary---<SERVICE_NAME>-<hash>.a.run.app without affecting production traffic.

Capture the canary URL from the output.