Workflow canaux natifs + OTA

Une configuration Capgo classique utilise un dev canal et un production canal de production. La CI envoie chaque bundle OTA vers dev, puis effectue une promotion vers production lorsque vous êtes prêt. Les équipes ajoutent souvent --fail-on-incompatible pour éviter que la CI ne déploie par erreur un live update nécessitant de nouveaux code natifs.

Cette page répond aux questions suivantes : que faire quand vous volontairement avez besoin d'un bundle incompatible avec les packages natifs actuels du canal ?

Si vous voulez comprendre pourquoi Capgo compare les packages natifs, commencez par Compatibilité native. Pour une branche CI complète qui choisit automatiquement entre l'OTA et Capgo Build, consultez Auto OTA ou natif.

Configuration de canal recommandée

Ce guide suppose que les dev et production canaux existent déjà. Créez-les d'abord si nécessaire :

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

Canal	Qui le reçoit	Upload typique
dev	Builds internes / QA	Chaque push CI de JS (et baselines natives intentionnelles)
production	Store users	Promu ou uploadé uniquement quand la release est prête

--fail-on-incompatible est une bonne option par défaut sur les deux canaux pour les uploads OTA quotidiens. Il compare les packages natifs du bundle que vous uploadez avec le bundle actuellement en ligne sur ce canal. S'ils diffèrent, l'upload échoue et rien n'est déployé.

OTA au quotidien (conserver le flag)

Lorsque le changement ne concerne que le JavaScript et que les packages natifs correspondent au canal :

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

--fail-on-incompatible empêche la dérive native accidentelle. --auto-min-update-version est requis lors de chaque upload une fois que le canal utilise la metadata stratégie (recommandée ci-dessous). Si le canal n'est pas encore sur metadata vous pouvez omettre --auto-min-update-version jusqu'au basculement.

Étape de CI optionnelle avant l'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 natif intentionnel (retirer le flag après)

Vous ne peut pas uploader un bundle nécessitant un nouveau code natif tout en gardant --fail-on-incompatible. Ce flag sert précisément à bloquer ce cas. Lorsqu'un plugin, une version de Capacitor, ou une autre dépendance native change volontairement :

1. Déployez la version correspondante binaire natif correspondant (App Store / Play Store, ou Build Capgo).
2. Envoyez le bundle JS correspondant sans --fail-on-incompatible.
3. Privilégiez --auto-min-update-version avec le canal sur la metadata stratégie pour que les appareils sur l'ancien binaire ne reçoivent pas le nouveau bundle avant d'installer la nouvelle app.
4. Après cet upload de base, repassez --fail-on-incompatible sur votre CI OTA habituelle (et gardez) --auto-min-update-version tant que le canal reste sur metadata).

1. Une seule fois par canal : activez le filtrage par métadonnées

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

   Répétez pour dev si ce canal reçoit également des baselines natives intentionnelles. Après ce changement, chaque upload vers le canal doit inclure --auto-min-update-version ou --min-update-version.

2. Déployez le binaire natif

   Compilez et soumettez l'application iOS/Android incluant les nouveaux plugins ou changements natifs. Tant que les utilisateurs n'ont pas installé ce binaire, ils ne peuvent pas exécuter en toute sécurité un bundle dépendant de ces packages natifs.

3. Envoyez la baseline OTA correspondante (pas de --fail-on-incompatible)

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

   Cela enregistre les nouveaux packages natifs sur le canal. Plus tard, bundle releaseType / --fail-on-incompatible vérifie l'utilisation de cette baseline.

4. Reprenez les uploads OTA sécurisés

   Les releases JS suivantes utilisent à nouveau ces deux flags :

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

Astuce

Considérez l'upload du native-baseline comme un job CI dédié (ou une étape de release manuelle), et non comme une exception ajoutée au job OTA par défaut. Le job par défaut doit toujours conserver --fail-on-incompatible, et sur un metadata canal, il doit également conserver --auto-min-update-version.

FAQ

Puis-je conserver --fail-on-incompatible et quand même envoyer un bundle incompatible avec le natif ?

Non. Si les packages natifs de l'upload diffèrent du bundle live du canal, le flag fait échouer la commande exprès. Pour une modification native intentionnelle, omettez le flag lors de cet upload (et utilisez --auto-min-update-version quand vous le pouvez).

Un upload unique sans le flag est-il la bonne approche ?

Oui. C'est la méthode supportée pour faire évoluer la base native du canal après avoir déployé un nouveau binaire. Gardez le flag sur tous les autres uploads OTA pour que tout dérive native accidentelle fasse échouer la CI.

Dois-je envoyer vers dev d'abord, puis vers production?

Oui, si cela correspond à votre processus. Appliquez les mêmes règles par canal: la vérification de compatibilité se fait par rapport au contenu en ligne sur le canal cible. Promouvez ou renvoyez un bundle vers production seulement après dev semble correct, et utilisez un upload native-baseline (sans --fail-on-incompatible) sur chaque canal nécessitant l'enregistrement des nouveaux packages natifs.

Et si j'envoie le nouveau bundle natif avec le flag toujours activé ?

La CI échoue et Capgo ne déploie pas cet upload. C'est le comportement attendu. Soit le changement était accidentel (corrigez les packages natifs et réessayez en OTA), soit il était intentionnel (utilisez le chemin natif ci-dessus).

Quel flag pour quel job ?

Chemin	Quand	Flags d'upload
l'OTA	JS uniquement ; les packages natifs correspondent au canal	--fail-on-incompatible + --auto-min-update-version (requis si le canal est activé metadata)
Base native	Nouveau binaire natif + bundle JS correspondant	Non --fail-on-incompatible; conserver --auto-min-update-version

Articles liés

Compatibilité native

Comment Capgo détecte l'écart de package natif et ce que signifie l'incompatibilité pour les appareils.

Auto OTA ou natif

Connectez bundle releaseType à GitHub Actions ou GitLab pour que la CI choisisse le bon chemin.

Ciblage de version

Canaux, règles semver et stratégie de métadonnées pour les paliers de déploiement.

CLI: bundle

Référence pour l'upload, la compatibilité, le releaseType et les flags associés.

Continuer après le workflow Native + OTA Channel

Si vous utilisez Workflow canaux natifs + OTA pour sécuriser les live updates lors des releases natives, connectez-l’avec Compatibilité native pour les règles de comparaison de packages, Auto OTA ou natif pour le branching CI, Ciblage de version pour les seuils de métadonnées, et la référence de bundle Capgo CLI pour les flags d'upload.