Workflow de canales Native + OTA

Una configuración común de Capgo usa un dev canal y un producción canal. El CI sube cada bundle OTA a dev, luego lo promociona a production cuando estés listo. Los equipos suelen añadir --fail-on-incompatible para que el CI no publique por error un live update que necesite nuevos code nativos.

Esta página responde a lo siguiente: ¿qué haces cuando intentionally un bundle incompatible con los paquetes nativos actuales del canal?

Si quieres saber por qué Capgo compara los paquetes nativos, empieza por Compatibilidad nativa. Para una rama de CI completa que elija entre OTA o Capgo Build automáticamente, consulta OTA automático o nativo.

Estructura de canales recomendada

Esta guía asume que los dev y production canales ya existen. Créalos primero si es necesario:

npx @capgo/cli@latest channel add production com.example.app
npx @capgo/cli@latest channel add dev com.example.app

Canal	Quién lo recibe	Upload típico
dev	Builds de QA / Internos	Cada push de JS en CI (y baselines nativas)
production	Almacenar usuarios	Promocionado o subido solo al estar listo

--fail-on-incompatible es un buen valor por defecto en ambos canales para uploads de OTA diarios. Compara los paquetes nativos del bundle que estás subiendo con el bundle actualmente activo en ese canal. Si difieren, el upload falla y no se despliega nada.

OTA del día a día (mantén el flag)

Cuando el cambio es solo JavaScript y los paquetes nativos coinciden con el canal:

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

--fail-on-incompatible evita el drift nativo accidental. --auto-min-update-version es necesario en cada upload una vez que el canal usa la metadata estrategia (recomendada abajo). Si el canal no está en metadata todavía, puedes omitir --auto-min-update-version hasta que hagas el cambio.

Gate de CI opcional antes del upload:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to upload with --fail-on-incompatible
# → native   stop; ship a native binary first (see below)

Bump nativo intencional (quita el flag una vez)

Usted no puede subir un bundle que requiera un nuevo code nativo mientras mantiene --fail-on-incompatible. Ese flag existe para bloquear precisamente ese caso. Cuando un plugin, la versión de Capacitor u otra dependencia nativa cambian a propósito:

1. Envía el correspondiente binario nativo (App Store / Play Store, o Build de Capgo).
2. Sube el bundle JS correspondiente sin --fail-on-incompatible.
3. Prefiere --auto-min-update-version con el canal en la metadata estrategia para que los dispositivos con el binario antiguo no reciban el nuevo bundle hasta que instalen la nueva app.
4. Tras esa carga inicial, vuelve --fail-on-incompatible al flujo normal de OTA CI (y mantén --auto-min-update-version mientras el canal permanezca en metadata).

1. Una vez por canal: activa el gating de metadatos

   npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

   Repetir para dev si ese canal también recibe baselines nativos intencionales. Tras este cambio, cada upload al canal debe incluir --auto-min-update-version o --min-update-version.

2. Lanzar el binario nativo

   Build y envía la app de iOS/Android que incluya los nuevos plugins o cambios nativos. Hasta que los usuarios instalen ese binario, no podrán ejecutar de forma segura un bundle que dependa de esos paquetes nativos.

3. Upload del baseline OTA correspondiente (no --fail-on-incompatible)

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --auto-min-update-version

   Esto registra los nuevos paquetes nativos en el canal. Más tarde, bundle releaseType / --fail-on-incompatible realiza checks usando ese baseline.

4. Reanudar uploads de OTA protegidos

   Los siguientes releases de solo JS usan ambos flags de nuevo:

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --fail-on-incompatible \
     --auto-min-update-version

Consejo

Trata la subida de native-baseline como un job de CI dedicado (o un paso de release manual), no como una excepción que añades al job de OTA por defecto. El job por defecto siempre debe mantener --fail-on-incompatible, y en un metadata channel también debería mantener --auto-min-update-version.

FAQ

¿Puedo mantener --fail-on-incompatible ¿y aun así subir un bundle incompatible con lo nativo?

No. Si los paquetes nativos del upload difieren del live bundle del canal, el flag hará fallar el comando a propósito. Para un cambio nativo intencional, omite el flag en ese upload (y usa --auto-min-update-version cuando puedas).

¿Es correcto hacer una subida única sin el flag?

Sí. Esa es la forma soportada de actualizar la base nativa del canal tras lanzar un nuevo binario. Mantén el flag en todos los demás uploads OTA para que cualquier desajuste nativo accidental siga fallando en CI.

Do I upload to dev primero, y luego a production?

Sí, si eso encaja con tu proceso. Ejecuta las mismas reglas por canal: la comprobación de compatibilidad se hace contra lo que esté activo en el canal de destino. Haz un promote o re-upload a production solo después de dev se ve bien, y usa un upload de native-baseline (sin --fail-on-incompatible) en cada canal que requiera registrar los nuevos paquetes nativos.

¿Qué pasa si subo el nuevo bundle nativo con el flag aún activado?

El CI falla y Capgo no publica ese upload. Ese es el resultado esperado. O el cambio fue accidental (corrige los paquetes nativos e inténtalo de nuevo como OTA), o fue intencionado (usa la ruta nativa de arriba).

¿Qué flag va en cada job?

Ruta	Cuando	Flags de upload
OTA	Solo JS; paquetes nativos coinciden con el canal	--fail-on-incompatible + --auto-min-update-version (requerido si el canal está en metadata)
Base nativa	Nuevo binario nativo + bundle JS coincidente	No --fail-on-incompatible; mantener --auto-min-update-version

Relacionado

Compatibilidad nativa

Cómo Capgo detecta cambios en paquetes nativos y qué significa la incompatibilidad para los dispositivos.

OTA automático o nativo

Conecta bundle releaseType con GitHub Actions o GitLab para que el CI elija la ruta correcta.

Segmentación por versión

Canales, reglas semver y la estrategia de metadatos para los mínimos de entrega.

CLI: bundle

Referencia para upload, compatibilidad, releaseType y flags relacionados.

Continuar desde el flujo Native + OTA Channel

Si estás usando Workflow de canales Native + OTA para mantener seguras las actualizaciones en vivo entre lanzamientos nativos, conéctalo con Compatibilidad nativa para las reglas de comparación de paquetes, OTA automático o nativo para el branching de CI, Segmentación por versión para los umbrales de metadatos, y el Capgo CLI referencia de bundle para los flags de upload.