Coordinar deploys de frontend y backend sin orquestado, usando Github Actions

El Setup

Un setup chiquito de SPA + API donde dos workflows de GitHub Actions
salen en paralelo en cada push a main. Probablemente un setup que no usaría en prod, pero algo que si uso para mis proyectos personales.

Ahora bien esto trae un problema de coordinación (el frontend llega a los usuarios antes de que exista el endpoint de la API), cuatro opciones, y el gate de ~80 líneas de bash que fue el ganador para nuestro caso de uso

El codebase: una SPA de React en CloudFront + S3, un backend FastAPI en AWS ECS Fargate, infraestructura en CDK.
Dos workflows (deploy-frontend.yml, deploy-backend.yml) disparados por push a main con path filters.

TL;DR

El approach simple aguanta mientras tu push esté dominado por
cambios de un solo dominio. Deja de funcionar cuando la mayoría de los pushes tocan los dos o más.

El problema

Dos workflows en la misma branch main:

# deploy-frontend.yml
on:
  push:
    branches: [main]
    paths: ["frontend/**"]

# deploy-backend.yml
on:
  push:
    branches: [main]
    paths: ["backend/**", "infra/**"]

Un push que toca los dos — digamos, "agrega el endpoint
/api/v1/leaderboard y la UI que lo llama" — dispara ambos workflows
en paralelo. Los builds de frontend normalmente son más rápidos (sin
Docker, sin rollout de ECS). Así que un usuario que refresca entre el
minuto 2 (SPA subida) y el minuto 6 (backend sano en ECS) pega contra
una SPA nuevecita apuntando a un endpoint que todavía no existe. La
consola del browser muestra un 404. Sentry pega un brinco, se disparan alertas de Cloudwatch, el usuario recarga, pega contra el caché, y ve el mismo error.

Difícil de cachar en dev porque el stack local arranca los dos servicios juntos. Fácil de cachar en prod una vez que pasa.

Las opciones

Opción 1: workflows paralelos independientes (el baseline de no hacer nada)

Con lo que arrancamos. Cada workflow escucha sus propios paths y
despliega en su propio tiempo. Cero coordinación.

# ambos workflows
on:
  push:
    branches: [main]
    paths: [...]

Pros:
cero setup, deploys de un solo dominio lo más rápido posible,
aislamiento total.
Contras:
la ventana de race de arriba. El costo solo aparece en los pushes acoplados.

Opción 2: colapsar en un solo workflow con orden explícito

El fix más "obvio": escribir un deploy.yml con deploy-backend como job 1 y deploy-frontend con needs: [deploy-backend].

jobs:
  deploy-backend:
    runs-on: self-hosted
    steps: [...]
  deploy-frontend:
    needs: [deploy-backend]
    runs-on: self-hosted
    steps: [...]

Pros:
modelo mental trivial; GitHub Actions maneja el orden.
Contras:
un push de solo-frontend ahora espera por un backend que no cambió (o
necesita un if: explícito para saltárselo, que es su propia
complejidad). Un step de lint flaky en el backend bloquea el deploy de frontend que ni siquiera dependía de los cambios del backend. Perdimos la independencia de path filters que hacía deseables los workflows paralelos para empezar.

Opción 3: el frontend gatea contra el SHA del backend (el gate simple)

Conservar los dos workflows. Agregar un step al inicio del workflow de frontend: si este commit también tocó backend, espera a que el
workflow de backend en el mismo SHA termine bien.

Pros:
cero overhead en pushes desacoplados (el caso común); se conserva
el paralelismo del caso común; el gate son ~80 líneas de bash + un
curl a la API de GitHub Actions. Sin infra nueva, sin servicio
orquestador, sin artifact pinning.

Contras:
bash. Polling. El gate corre en el runner del frontend, así
que cuesta minutos de runner mientras espera (gratis en self-hosted,
facturable en ubuntu-latest).

Opción 4: pin del frontend a un artifact buildeado del backend

La respuesta correcta de principio: cada build de frontend embebe la
versión de backend contra la que se construyó; la SPA se niega a llamar una API que no haga match.

// frontend
const REQUIRED_API_VERSION = "2026.05.27.a"; // inyectado en el build
if (apiHealthcheck.version !== REQUIRED_API_VERSION) showStaleBanner();

Pros:
cero ventana de race incluso con rollouts totalmente independientes; el cliente puede caer a un banner de "refresca para actualizar"; funciona durante rollbacks.
Contras:
cada cambio de endpoint se vuelve un contrato versionado; necesitas un endpoint de discovery /api/version y lógica en la SPA para manejar el mismatch; coordinar across clientes móviles eventualmente cuesta más que el gate.

Cómo elegir

Patrón de push	Mejor opción
Pushes mayormente de un solo dominio	Opción 3 (gate)
Pushes mayormente acoplados	Opción 2 (un solo workflow)
Clientes de larga vida / móvil / offline / una app de escritorio que no puedes forzar a refrescar	Opción 4 (contrato versionado)

Nuestra distribución: ~80% solo-backend, ~15% solo-frontend, ~5%
acoplado. La Opción 3 fue el match obvio. El resto del post es su
evolución.

Etapa 0: el punto de partida

Dos workflows, sin coordinación:

# .github/workflows/deploy-frontend.yml
name: Deploy Frontend
on:
  push:
    branches: [main]
    paths:
      - "frontend/**"
      - ".github/workflows/deploy-frontend.yml"
jobs:
  build-and-deploy:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v5
      - run: pnpm install --frozen-lockfile && pnpm build
      - run: aws s3 sync dist s3://myapp-frontend
      - run: aws cloudfront create-invalidation --distribution-id $DIST_ID --paths '/*'

Push acoplado → race → 404s en producción.
Fix: gatear el deploy de frontend contra el de backend cuando el commit cambió código de backend.

Etapa 1: detectar el push acoplado

Antes de hacer nada más, el gate tiene que responder: ¿este commit de verdad tocó el backend? Si no, no esperamos, procede de inmediato y no desperdicies un minuto de runner.

- uses: actions/checkout@v5
  with:
    # Necesitamos ≥ 2 commits para diffear contra el padre.
    fetch-depth: 2

- name: Detect coupled push
  run: |
    set -euo pipefail
    changed=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || true)
    if ! echo "$changed" | grep -qE "^(backend/|infra/|\.github/workflows/deploy-backend\.yml$)"; then
      echo "No backend/infra changes — proceeding."
      exit 0
    fi
    echo "Backend changes detected — gate engaged."

El patrón de paths espeja el bloque paths: de deploy-backend.yml
exactito — si un path dispara el workflow de backend, el gate tiene que esperarlo. La diferencia entre los dos es la causa #1 de false
proceeds, así que mantenlos pegaditos en el code review.

El fetch-depth: 2 es la trampa — actions/checkout@v5 viene por
default en shallow 1, y git diff HEAD~1 en un checkout de depth-1
regresa nada en silencio, lo cual el script lee como "no hay cambios de backend — procede". (Pegamos contra esto en el primer deploy después de shipear el gate. Cáchalo con un guard, no nomás con documentación.)

Etapa 2: hacer poll al run del backend por SHA

Ahora sabemos que hay que esperar. El mecanismo es la REST API de
GitHub Actions filtrada por head_sha:

api="https://api.github.com/repos/${GITHUB_REPOSITORY}/actions/workflows/deploy-backend.yml/runs"
query="head_sha=${GITHUB_SHA}&per_page=1"

for i in $(seq 1 160); do  # techo de 40 min a 15s/poll
  payload=$(curl -sS \
    -H "Authorization: Bearer ${GH_TOKEN}" \
    -H "Accept: application/vnd.github+json" \
    "${api}?${query}")
  status=$(echo "$payload" | jq -r '.workflow_runs[0].status // empty')
  conclusion=$(echo "$payload" | jq -r '.workflow_runs[0].conclusion // empty')
  if [ "$status" = "completed" ]; then
    case "$conclusion" in
      success|skipped) exit 0 ;;
      *) echo "::error::Backend ${conclusion}"; exit 1 ;;
    esac
  fi
  sleep 15
done
echo "::error::Timed out waiting for backend deploy."; exit 1

El filtro head_sha es el eje de todo — regresa el run de este commit exacto, no "el último run en main", que haría race con un push de fast-follow.

El permiso actions: read se tiene que agregar al bloque permissions: del workflow — sin eso la API regresa 403 y el gate
falla open en silencio.

Etapa 3: manejar el "todavía no se registra"

El primer run en prod reveló un race: el workflow de frontend puede
arrancar antes de que GitHub haya registrado el run del workflow de
backend en el mismo SHA. La API regresa total_count: 0, el script lee "no hay run de backend en este SHA, procede", y ya volvimos al problema original del 404.

Fix: una grace window. Dale a GitHub hasta 30s para registrar el run.

# Grace window — espera hasta 30s a que aparezca el run de backend.
for i in $(seq 1 6); do
  count=$(curl ... | jq -r '.total_count')
  [ "$count" != "0" ] && break
  sleep 5
done

Los 30s son empíricos — medí unos cuantos pushes acoplados, el delay de registro siempre fue < 10s pero brincó a 18s una vez durante un
incidente de GitHub. 30s es lo suficientemente generoso como para que
no hagamos false-proceed; el timeout exterior de 40 minutos absorbe el costo.

Si después de 30s el run sigue sin existir, el script sí cae a "no
hay run en este SHA — procede". Esa es la decisión correcta: o el
workflow de backend no se disparó (el path filter excluyó los cambios), o GitHub está tan degradado que un deploy de frontend es el menor de nuestros problemas. No le busques tres pies al gato.

Etapa 4: superficies de error con sentido

Dos modos de falla necesitan manejo explícito para que el dev que ve el build en rojo pueda actuar:

# 1. La API de GitHub regresa 4xx (auth, rate limit, etc.).
fetch_runs() {
  local response status body
  response=$(curl -sS -w "\n%{http_code}" ...)
  status=$(echo "$response" | tail -n1)
  body=$(echo "$response" | sed '$d')
  if [ "$status" != "200" ]; then
    echo "::error::GitHub API returned ${status}: ${body}" >&2
    return 1
  fi
  echo "$body"
}

curl -f sale con 22 sin body. El wrapper conserva el body para que el log de error diga "403 Forbidden: actions read permission missing" en lugar de "exit code 22, suerte".

# 2. El deploy de backend falló — saca la conclusion tal cual.
*) echo "::error::Backend deploy ${conclusion}. Abortando el deploy de frontend para que la SPA nunca apunte a una API ausente." ;;

Los casos failure|cancelled|timed_out todos colapsan a la misma
acción (no deployar el frontend), pero imprimir la conclusion exacta te ahorra un click hacia el run del workflow de backend cuando estás
investigando.

El resultado

Un setup de dos workflows que:

• Cuesta 0 segundos en pushes desacoplados (el caso del 80%)
• Cuesta a lo mucho el wall time del deploy de backend en pushes acoplados
• Falla closed — si el deploy de backend falla, el frontend no shipea (sin tormenta de 404s)
• Falla closed en el gate mismo — mala respuesta de API, timeout, permiso caído, todos salen con 1

Desde que lo shipeamos (medido sobre seis semanas):

• 47 pushes acoplados deployados limpio
• 3 pushes acoplados donde el gate cachó un deploy de backend fallido antes de que el frontend saliera (habría sido un outage visible para el usuario)
• 0 casos de gate haciendo false-proceed

Lo que NO ayudó

• Intentar detectar "cambios de endpoint de API" desde el diff. Un cambio en un campo de schema de Pydantic basta), y los false negatives aquí son peores que los false positives. El check de path por git-diff es suficientemente bueno.
• Cancel-in-progress en el workflow de frontend. Se ve atractivo matar el deploy de frontend en vuelo si llega un push nuevo — pero el cancel pasa a media S3-sync, dejando el bundle a medio subir. Combinado con un caché stale de CloudFront esto es peor que el race condition original. Lo dejamos en cancel-in-progress: false.

Qué sí ayudaría a futuro

1. Mover la lógica del gate a un action reutilizable (actions/wait-for-workflow@v1). Las ~80 líneas de bash funcionan pero están medio copy-pasteadas entre proyectos.
2. Sacar el conteo de pushes acoplados a un dashboard.** Si el ratio se va del 5% hacia el 30%, el gate simple deja de ser la herramienta correcta.
3. Hacer el deploy de backend más rápido para que la espera sea más corta cuando sí se active.

Lecciones

• Los path filters definen qué cosas tus workflows acuerdan que los disparan. Mantenlos juntos y revísalos juntos.
• El filtro head_sha en la API de Actions es lo más útil de todo esto. Existe, es estable, está documentado, y convierte "¿en cuál run estoy esperando?" de un problema difícil a un solo query.