Despliegues progresivos

Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.

Un despliegue progresivo mantiene la versión de un canal versión estable de fallback activa mientras entrega uno aparte objetivo de rollout a un subconjunto controlado de dispositivos. La mayoría de los usuarios en producción siguen en estable. Solo el grupo de despliegue recibe la candidata hasta que Completar rollout o Rollback del rollout.

Controles de rollout progresivo en un canal Capgo — El **sección de Rollout progresivo** la sección de la pestaña Information de un canal muestra **Objetivo del rollout** y **Fallback estable**, controles de porcentaje y acciones de rollout.

Cómo funcionan los rollouts progresivos de extremo a extremo

Cada canal puede tener dos enlaces de bundle al mismo tiempo:

Etiqueta de consola	API / CLI	Quién lo recibe
Fallback estable	Bundle estable (`version` en POST de canales)	Cada dispositivo del canal que está necesitas en la cohorte de despliegue.
Objetivo del rollout	Objetivo del despliegue (`rolloutVersion` / `rollout_version`)	Solo los dispositivos que Capgo selecciona aleatoriamente para la cohorte de despliegue mientras el despliegue está activado y no está en pausa.

Qué ocurre en cada comprobación de actualización

El dispositivo solicita a Capgo una actualización en su canal.
Si el rollout está desactivado, o no hay objetivo, Capgo sirve la versión estable de fallback.
Si el rollout está activado y en pausa, los dispositivos que ya están en el cohorte mantienen el objetivo de rollout; el resto recibe la versión estable de fallback.
Si el rollout está activado y no está en pausa, Capgo comprueba si este dispositivo está en el cohorte de rollout:
- En el cohorte → objetivo de rollout.
- Fuera del cohorte → fallback estable.

Capgo toma una decisión aleatoria para cada dispositivo elegible y luego la guarda en caché usando un hash del ID del dispositivo y del ID del rollout. Esto hace que la cohorte sea persistente durante la duración de caché configurada, en lugar de volver a sortear en cada comprobación de actualización.

Activar un rollout

Un rollout necesita primero un fallback estable. En el dashboard, asigna el bundle estable antes de elegir el objetivo del rollout. Con los Canales públicos API, un canal existente puede proporcionar version y rolloutVersion en la misma solicitud POST.

Para iniciar la entrega:

Configura la Objetivo del rollout (o sube/asigna un bundle — ver Subir y asignar bundles).
Elige un porcentaje y haz clic en Aplicar porcentaje.
Haz clic Activar rollout.

Hasta que actives el rollout, configurar un target y un porcentaje no cambia lo que reciben los dispositivos.

Cambios en el porcentaje

En la consola, edita el porcentaje y haz clic en Aplicar porcentaje para guardarlo. Capgo conserva las decisiones existentes cuando es posible:

Aumentar un porcentaje — los dispositivos ya seleccionados siguen seleccionados; solo se añade un subconjunto aleatorio de dispositivos no seleccionados previamente.
Disminuir un porcentaje — un subconjunto aleatorio del grupo seleccionado vuelve al fallback estable.
Establecer el porcentaje en 0% — no se seleccionan dispositivos nuevos. Los dispositivos que ya ejecutan el target de rollout habilitado seguirán recibiéndolo hasta que lo deshabilites, hagas rollback o cambies el target.
Pausar rollout — impide que entren nuevos dispositivos, mientras que los dispositivos que ya ejecutan el target habilitado permanecen en él.
Desactivar rollout — deja de resolver el objetivo del rollout; las comprobaciones de update usarán el fallback estable.

Subir y asignar bundles

En canales con rollout progresivo configurado, las nuevas subidas y los enlaces de bundles van al objetivo de rollout por defecto. Fallback estable permanece sin cambios a menos que elijas reemplazarlo explícitamente.

Al subir o vincular un bundle a un canal con rollout configurado, la consola muestra el título Este canal usa despliegue progresivo y el banner:

Las nuevas subidas y los enlaces de bundles en este canal van al destino del rollout por defecto. Stable permanece sin cambios a menos que elijas reemplazarlo.

Elige dónde debe ir el bundle:

Opción de la consola	Cuándo usarlo
Auto (recomendado)	Predeterminado. Igual que Objetivo del rollout cuando se configura un despliegue progresivo; igual que Reemplazar estable cuando no. Coincide con API `target: "auto"` y las subidas de CLI sin `--stable` o `--rollout`.
Objetivo del rollout	Publica un candidato; el fallback estable se mantiene igual.
Reemplazar estable	Reemplazar intencionalmente la versión estable de producción (escape hatch).

La pista Auto usa rollout cuando progressive está configurado se aplica a API target: "auto" y a las subidas de CLI que no pasan --stable o --rollout.

Enrutamiento de subida por defecto

Estado del canal	Subida / asignación por defecto	Fallback estable	Objetivo del rollout
No rollout progresivo configurado	Llega al canal	Asignado a la subida	N/D
Despliegue progresivo configurado	Llega al canal	Sin cambios	Asignado a la subida

Rutas de CLI y API

Cómo publicas el bundle	Fallback estable	Objetivo del rollout	Notas
`bundle upload --channel <name>` (sin flags adicionales)	Sin cambios en los canales de rollout; configura cuando no hay rollout	Configurar en los canales de rollout	Coincide con el default de consola.
`bundle upload --channel <name> --rollout <percent>`	Sin cambios	Configurar; rollout activado en ese porcentaje	Subida y activación en un paso.
`bundle upload --channel <name> --stable`	Reemplazado	Sin cambios	Escape hatch: reemplazo estable intencional.
`bundle upload` con no `--channel`	Sin cambios	Sin cambios	Solo registrar; vincular con `channel set` o API.
Diálogo de enlace en consola → Auto (recomendado)	Sin cambios en los canales de rollout	Configurar en los canales de rollout	Opción predeterminada.
Diálogo de enlace en consola → Objetivo del rollout	Sin cambios	Configurar	Objetivo de rollout explícito.
Diálogo de enlace en consola → Reemplazar estable	Reemplazado	Sin cambios	Válvula de escape.
PUT `/bundle/` con `target: "auto"`	Sin cambios en los canales de rollout	Configurar en los canales de rollout	Predeterminado de API.
PUT `/bundle/` con `target: "rollout"`	Sin cambios	Configurar	Objetivo de rollout explícito.
PUT `/bundle/` con `target: "stable"`	Reemplazado	Sin cambios	Válvula de escape.
`channel set --bundle <version>`	Reemplazado	Sin cambios	Override explícito a estable.
`channel set --rollout-bundle <version>` (+ `--rollout-percentage`, `--rollout-enable`)	Sin cambios	Establecido o cambiado	Configura el target sin subir nada.
POST de canales `version`	Reemplazado cuando se define	Sin cambios	Override explícito a estable.
POST de canales `rolloutVersion`	Sin cambios	Establecido o cambiado cuando se define	Asignación programática de objetivos.

Ejemplos de CLI

Subida por defecto en un canal con rollout configurado (objetivo de rollout; stable sin cambios):

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production

Sube, establece el objetivo de rollout y habilita al 5%:

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --rollout 5

Reemplaza stable explícitamente:

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --stable

Sube sin vincular y luego configura el rollout:

bunx @capgo/cli@latest bundle upload com.example.app --path ./dist -b 1.3.0

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-bundle 1.3.0 \
  --rollout-percentage 5 \
  --rollout-enable

API asignar con destino explícito (auto | stable | rollout):

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version_id": 456,
    "channel_id": 789,
    "target": "rollout"
  }' \
  https://api.capgo.app/bundle/

Aumenta la exposición sin reasignar dispositivos ya seleccionados:

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-percentage 25

Usa --rollout-percentage-bps cuando necesitas pasos más finos que porcentajes enteros (por ejemplo 50 = 0.5%).

Consulta la Referencia del canal CLI y referencia del bundle CLI para cada opción de rollout. La UX de la consola se publica en capgo.app#3313.

Sección de despliegue progresivo (dashboard)

Abrir una app → Canales → elegir el canal → Información → sección de Rollout progresivo.

La sección muestra Objetivo del rollout y Fallback estable para los dos enlaces de bundle. Usa Cambiar objetivo de rollout para elegir un bundle candidato diferente. Después de editar el porcentaje, haz clic en Aplicar porcentaje para guardarlo.

Control	What it does	Dispositivos ya en la cohorte	Nuevos dispositivos elegibles
Cambiar objetivo de rollout	Configura `rolloutVersion`. Al cambiarlo, se inicia un nuevo ID de rollout y una nueva cohorte. Subir o asignar un bundle al canal (por defecto) también establece el objetivo del rollout.	Mantén el objetivo anterior hasta que vuelvan a hacer check-in y coincidan con las nuevas reglas de decisión.	Seleccionado según el porcentaje respecto al nuevo objetivo.
Aplicar porcentaje	Guarda el porcentaje introducido.	Se conserva al aumentar; al disminuir, un subconjunto aleatorio podría quedar fuera.	Añadido o excluido según las reglas de porcentaje anteriores.
Activar rollout	Activa la entrega del rollout para el objetivo y porcentaje configurados.	Sin cambios inmediatos hasta la próxima comprobación de actualización.	Podría ser seleccionado en la próxima comprobación.
Pausar rollout	Evita que entren nuevos dispositivos.	Mantener el objetivo del rollout.	Recibir fallback estable en la próxima comprobación.
Reanudar rollout	Elimina la pausa.	Sin cambios.	Podría seleccionarse de nuevo en la próxima comprobación.
Desactivar rollout	Deja de resolver el objetivo del rollout; Capgo usa fallback estable para todos.	Pasar a fallback estable en la próxima comprobación.	Recibe el fallback estable.
Completar rollout (API: `promoteToStable`; CLI: `--rollout-promote`)	Establece el rollout como el nuevo fallback estable y luego limpia el estado del rollout. Confirmado por ¿Completar el rollout progresivo? — el target pasa a ser estable para todos, se reemplaza el fallback estable anterior y el porcentaje se reinicia.	Convertir en fallback estable para todos.	Recibe el bundle completado como estable.
Rollback del rollout (API: `rollback`; CLI: `--rollout-rollback`)	Limpia el target, desactiva el rollout, resetea el porcentaje a 0% y devuelve los dispositivos al fallback estable.	Volver al fallback estable en la próxima comprobación.	Recibe el fallback estable.

Ejecuta una acción de terminal a la vez (Completar rollout y Rollback del rollout no se pueden combinar en una sola llamada a API):

# Stop adding devices while you investigate
bunx @capgo/cli@latest channel set production com.example.app --rollout-pause

# Allow new devices to enter again
bunx @capgo/cli@latest channel set production com.example.app --rollout-resume

# Complete rollout — candidate becomes stable for everyone
bunx @capgo/cli@latest channel set production com.example.app --rollout-promote

# Rollback rollout — discard candidate and return to stable
bunx @capgo/cli@latest channel set production com.example.app --rollout-rollback

Mantén disponible el bundle objetivo del rollout hasta que Completar rollout o Rollback del rollout. Los bundles vinculados como fallback estable o objetivo del rollout están protegidos contra la eliminación.

Workflow seguro

El rollout progresivo está diseñado para que puedas validar en producción sin cambiar todo el canal de golpe. Una secuencia práctica:

Confirma que el fallback estable funciona bien. Debe ser la versión que estés dispuesto a seguir sirviendo a la mayoría de los usuarios.
Sube el candidato al canal configurado para el rollout (bundle upload --channel <name> llega a Objetivo del rollout y deja Fallback estable sin cambios) o usa --rollout <small-percent> para habilitar la exposición en el mismo paso.
Empieza con poco — 1–5% es suficiente para la primera señal. Haz clic en Aplicar porcentaje, luego Activar rolloutActiva la pausa automática si quieres que Capgo detenga la exposición cuando las tasas de fallo aumenten.
Monitorea antes de ampliar. Usa Observe para la salud de la versión, Análisis de logs para patrones de error y el canal Historial para los cambios de configuración. Compara el objetivo del rollout con el fallback estable; no subas el porcentaje hasta que la cohorte se vea saludable.
Aumenta gradualmente — edita el porcentaje, haz clic en Aplicar porcentaje, y ve subiendo (por ejemplo, 5% → 25% → 50% → 100%). Capgo mantiene seleccionados los dispositivos que ya están en la cohorte cuando aumentas.
Completa el rollout cuando estés seguro — confirma ¿Completar el rollout progresivo? para que el candidato se convierta en el fallback estable para todos.
Si algo va mal, pausa el rollout primero — detiene la nueva exposición mientras investigas. Los dispositivos que ya están en el build defectuoso siguen en él hasta que Rollback del rollout o Desactivar rollout.

Política de pausa automática

Capgo puede evaluar un despliegue habilitado cada cinco minutos y actuar cuando su señal de fallo supere tu umbral. Mide las instalaciones y los fallos para el objetivo del despliegue en el canal y la ventana de tiempo seleccionados, y luego utiliza un límite inferior de confianza de Wilson en lugar de solo la tasa bruta de fallos.

La pausa automática está desactivada por defecto. Configura estos campos en el canal Información pestaña o con channel set:

Umbral de tasa de fallos en puntos básicos (500 = 5%). Se requiere un umbral para activar la política.
Ventana en minutos (por defecto: 60).
Confianza entre 0 y 1 (por defecto: 0.95).
Intentos y fallos mínimos opcionales, para evitar actuar con muestras pequeñas.
Cooldown en minutos (predeterminado: 60), lo que previene acciones repetidas.
Acción: pause, rollback, o notify.

pause detiene la exposición a nuevos rollouts, rollback limpia el objetivo y vuelve al fallback estable, y notify envía una alerta de rollout sin cambiar la entrega del rollout.

bunx @capgo/cli@latest channel set production com.example.app \
  --auto-pause-enabled \
  --auto-pause-failure-rate-bps 500 \
  --auto-pause-window-minutes 60 \
  --auto-pause-confidence 0.95 \
  --auto-pause-min-attempts 100 \
  --auto-pause-min-failures 5 \
  --auto-pause-action pause \
  --auto-pause-cooldown-minutes 120

Puntos de entrada de API y del dashboard

Dashboard: app → Canales → canal → Información → sección de Rollout progresivo
Canales API: Canales públicos API para campos de rollout, promoción y rollback
Asignación de bundle API: PUT /bundle/ con target: auto, stable, o rollout

Para la enrutación general de canales y la precedencia de dispositivos, consulta Canales. Para la recuperación de emergencia de un bundle fuera de un despliegue progresivo, consulta Reversión de un live update.