Déploiements progressifs

Un déploiement progressif maintient en place le fallback stable d'un canal tout en livrant une cible de déploiement à un sous-ensemble contrôlé d’appareils. La majorité des utilisateurs en production restent sur la version stable. Seule la cohorte de déploiement reçoit la version candidate jusqu’à ce que Terminer le déploiement ou Rollback du déploiement.

Le Déploiement progressif de l'onglet Information d'un canal affiche Cible du déploiement et Fallback stable, le contrôle du pourcentage et les actions de déploiement.

Fonctionnement complet du déploiement progressif

Chaque canal peut avoir deux liens de bundle simultanément :

Étiquette de console	API / CLI	Destinataires
Fallback stable	Bundle stable (version sur POST des canaux)	Chaque appareil du canal qui est pas dans la cohorte de déploiement.
Cible du déploiement	Cible du déploiement (rolloutVersion / rollout_version)	Seuls les appareils que Capgo sélectionne aléatoirement pour le groupe de déploiement pendant que le déploiement activé et non en pause.

What happens on each update check

1. L’appareil demande à Capgo une mise à jour sur son canal.
2. Si le déploiement est désactivé, ou s’il n’y a pas de cible, Capgo sert la fallback stable.
3. Si le déploiement progressif est activé et en pause, les appareils déjà dans la cohorte conservent la cible de déploiement ; tous les autres reçoivent fallback stable.
4. Si le déploiement progressif est activé et non en pause, Capgo vérifie si cet appareil fait partie de la cohorte de déploiement :
   • Dans la cohorte → cible du déploiement.
   • Hors du cohort → repli stable.

Capgo prend une décision aléatoire pour chaque appareil éligible, puis la met en cache à l’aide d’un hash de l’ID de l’appareil et de l’ID du déploiement. Cela rend le cohort sticky pour la durée de cache configurée, au lieu de re-déployer à chaque vérification de mise à jour.

Sticky ne signifie pas permanent

La durée de cache par défaut pour la décision de déploiement est de 30 jours. Une fois expirée, un appareil peut être sélectionné à nouveau. Modifier la cible du déploiement crée un nouvel ID de déploiement et démarre un nouveau cohort. Vous pouvez définir la durée de cache entre 60 secondes et 365 jours.

Activer un déploiement progressif

Un déploiement nécessite d’abord un repli stable. Dans le dashboard, assignez le bundle stable avant de choisir la cible du déploiement. Avec le Canaux publics API, un canal existant peut fournir version et rolloutVersion dans la même requête POST.

Pour démarrer la livraison :

1. Fixez le Cible du déploiement (ou envoyer/assigner un bundle — voir Envoyer et assigner des bundles).
2. Choisissez un pourcentage et cliquez sur Appliquer le pourcentage.
3. Cliquez Activer le déploiement progressif.

Jusqu’à l’activation du déploiement progressif, la configuration d’une cible et d’un pourcentage ne modifie pas les appareils concernés.

Modifications du pourcentage

Dans la console, modifiez le pourcentage et cliquez sur Appliquer le pourcentage pour l’enregistrer. Capgo conserve les décisions existantes lorsque c’est possible :

• Augmenter un pourcentage — les appareils déjà sélectionnés le restent ; seul un sous-ensemble aléatoire d’appareils précédemment non sélectionnés est ajouté.
• Diminuer un pourcentage — un sous-ensemble aléatoire de la cohorte sélectionnée revient au fallback stable.
• Réglez le pourcentage à 0 % — aucun nouvel appareil n'est sélectionné. Les appareils qui utilisent déjà la cible de déploiement progressif activée continuent de recevoir cette cible jusqu'à ce que vous la désactiviez, fassiez un rollback ou changiez de cible.
• Suspendre le déploiement progressif — empêche les nouveaux appareils d'y accéder, tandis que ceux qui utilisent déjà la cible activée y restent.
• Désactiver le déploiement progressif — stops resolving the rollout target; update checks use the stable fallback.

Envoyer et assigner des bundles

Sur les canaux par déploiement progressif configuré, les nouveaux uploads et liens de bundle sont envoyés vers le cible de déploiement par défaut. Fallback stable reste inchangé, sauf si vous choisissez explicitement de le remplacer.

Ce canal utilise un déploiement progressif

Lorsque vous envoyez ou liez un bundle à un canal configuré pour un déploiement progressif, la console affiche le titre Ce canal utilise un déploiement progressif et le bandeau :

Les nouveaux uploads et liens de bundle sur ce canal sont envoyés par défaut à la cible du déploiement progressif. Stable reste inchangé, sauf si vous choisissez de le remplacer.

Choisissez la destination du bundle :

Choix dans la console	Quand l’utiliser
Auto (recommandé)	Par défaut. Identique à Cible du déploiement lorsqu’un déploiement progressif est configuré ; identique à Remplacer la version stable sinon. Correspond à API target: "auto" et aux uploads CLI sans --stable ou --rollout.
Cible du déploiement	Déployez un candidat ; le repli stable reste inchangé.
Remplacer la version stable	Remplacer intentionnellement la version stable de production (file de sortie).

L’indice Auto utilise le rollout quand le mode progressif est configuré s'applique à API target: "auto" et aux uploads CLI qui ne passent pas --stable ou --rollout.

Routage d'upload par défaut

État du canal	Upload / assignation par défaut	Fallback stable	Cible du déploiement
Non déploiement progressif configuré	Atterri sur le canal	Défini sur l’upload	N/A
Déploiement progressif configuré	Atterri sur le canal	Inchangé	Défini sur l’upload

Chemins CLI et API

Comment vous déployez le bundle	Fallback stable	Cible du déploiement	Notes
bundle upload --channel <name> (aucun flag supplémentaire)	Inchangé sur les canaux de déploiement progressif ; configurer lorsqu'aucun déploiement progressif n'est actif	Définissez sur les canaux de déploiement progressif	Correspond au défaut de la console.
bundle upload --channel <name> --rollout <percent>	Inchangé	Définissez; rollout activé à ce pourcentage	Upload en une étape + activation.
bundle upload --channel <name> --stable	Remplacé	Inchangé	Filet de sécurité — remplacement stable intentionnel.
bundle upload par non --channel	Inchangé	Inchangé	Enregistrement uniquement ; associer avec channel set ou API.
Boîte de dialogue de lien console → Auto (recommandé)	Inchangé sur les canaux de déploiement	Définissez sur les canaux de déploiement progressif	Choix par défaut.
Boîte de dialogue de lien console → Cible du déploiement	Inchangé	Définissez	Cible de déploiement explicite.
Boîte de dialogue de lien console → Remplacer la version stable	Remplacé	Inchangé	File de secours.
PUT /bundle/ par target: "auto"	Inchangé sur les canaux de déploiement	Définissez sur les canaux de déploiement progressif	par défaut de API.
PUT /bundle/ par target: "rollout"	Inchangé	Définissez	Cible de déploiement explicite.
PUT /bundle/ par target: "stable"	Remplacé	Inchangé	Solution de repli.
channel set --bundle <version>	Remplacé	Inchangé	Override stable explicite.
channel set --rollout-bundle <version> (+ --rollout-percentage, --rollout-enable)	Inchangé	Défini ou modifié	Configurer la cible sans upload.
Canaux POST version	Remplacé when set	Inchangé	Override stable explicite.
Canaux POST rolloutVersion	Inchangé	Défini ou modifié when set	Affectation programmatique des cibles.

Exemples CLI

Upload par défaut sur un canal configuré pour un rollout (cible du rollout ; stable inchangé) :

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

Upload, définition de la cible du rollout et activation à 5 % :

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

Remplacer explicitement la version stable :

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

Envoyez sans lien, puis configurez le déploiement progressif :

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 assigner avec une cible explicite (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/

Augmentez l'exposition sans réassigner les appareils déjà sélectionnés :

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

Utiliser --rollout-percentage-bps quand vous avez besoin de paliers plus fins que des pourcentages entiers (par exemple 50 = 0.5%).

Consultez le référence du canal CLI et référence du bundle CLI for every rollout option. Console UX ships in capgo.app#3313.

Section déploiement progressif (dashboard)

Ouvrir une app → Canaux → choisir le canal → Informations → Déploiement progressif.

La section affiche Cible du déploiement et Fallback stable pour les deux liens de bundle. Utilisez Modifier la cible du déploiement progressif pour choisir un autre bundle candidat. Après avoir modifié le pourcentage, cliquez sur Appliquer le pourcentage pour l’enregistrer.

Contrôle	Ce qu’il fait	Appareils déjà dans la cohorte	Nouveaux appareils éligibles
Modifier la cible du déploiement	Définit rolloutVersion. Le modifier crée un nouvel ID de rollout et une nouvelle cohorte. L'upload ou l'affectation d'un bundle au canal (par défaut) définit aussi la cible du rollout.	Conservez la cible précédente jusqu'à ce qu'ils se reconnectent et correspondent aux nouvelles règles de décision.	Sélectionné selon le pourcentage appliqué à la nouvelle cible.
Appliquer le pourcentage	Enregistre le pourcentage saisi.	Préservé lors d'une augmentation ; un sous-ensemble aléatoire peut être retiré lors d'une diminution.	Ajouté ou exclu selon les règles de pourcentage ci-dessus.
Activer le déploiement progressif	Active la diffusion du rollout pour la cible et le pourcentage configurés.	No immediate change until the next update check.	May be selected on the next check.
Suspendre le déploiement progressif	Empêche les nouveaux appareils de rejoindre.	Rester sur la cible du déploiement.	Recevoir la version stable de secours au prochain contrôle.
Reprendre le déploiement	Lève la pause.	Inchangé.	Peut être sélectionné à nouveau lors du prochain contrôle.
Désactiver le déploiement progressif	Arrête la résolution de la cible du déploiement ; Capgo utilise la version stable de secours pour tout le monde.	Passer à la version stable de secours au prochain contrôle.	Recevoir la version stable de secours.
Terminer le déploiement (API: promoteToStable; CLI: --rollout-promote)	Définit la nouvelle version stable comme fallback par défaut, puis réinitialise l'état du déploiement. Confirmé par Terminer le déploiement progressif ? — la cible devient stable pour tout le monde, l'ancienne version stable de secours est remplacée et le pourcentage est réinitialisé.	Devenir la version stable de secours pour tous.	Recevoir le bundle finalisé comme stable.
Rollback du déploiement (API: rollback; CLI: --rollout-rollback)	Efface la cible, désactive le déploiement progressif, remet le pourcentage à 0 % et renvoie les appareils vers la version stable.	Revenir à la version stable de secours au prochain contrôle.	Recevoir la version stable de secours.

Utilisez une action terminale à la fois (Terminer le déploiement et Rollback du déploiement ne peuvent pas être combinés dans un seul appel 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

Gardez le bundle cible du rollout disponible jusqu'à ce que vous Terminer le déploiement ou Rollback du déploiement. Les bundles liés en tant que fallback stable ou cible de rollout sont protégés contre la suppression.

Workflow sécurisé

Le déploiement progressif est conçu pour vous permettre de valider en production sans basculer l'ensemble du canal d'un coup. Une séquence pratique :

1. Vérifiez que le repli stable est opérationnel. Elle doit correspondre à la version que vous souhaitez continuer à servir à la majorité des utilisateurs.
2. Envoyez la version candidate vers le canal de déploiement progressif (bundle upload --channel <name> arrive sur Cible du déploiement et laisse Fallback stable tranquille) ou utilisez --rollout <small-percent> pour activer l'exposition dans la même étape.
3. Commencez petit — 1 à 5 % suffisent pour un premier signal. Cliquez sur Appliquer le pourcentage, puis Activer le déploiement progressif. Activez la pause automatique si vous voulez que Capgo arrête l'exposition lorsque les taux d'échec grimpent.
4. Surveillez avant d'élargir. Utiliser Observe pour la santé de la version, Analyse des logs pour les motifs d'erreur, et l'onglet Canal Historique pour les changements de configuration. Comparez la cible du déploiement avec la version stable de secours ; n'augmentez pas le pourcentage tant que la cohorte ne semble pas saine.
5. Augmenter progressivement — modifiez le pourcentage, cliquez Appliquer le pourcentage, et augmentez progressivement (par exemple 5 % → 25 % → 50 % → 100 %). Capgo conserve les appareils déjà dans la cohorte sélectionnée lorsque vous augmentez le pourcentage.
6. Finaliser le déploiement progressif une fois confiant — confirmer Terminer le déploiement progressif ? afin que la version candidate devienne le fallback stable pour tous.
7. En cas de problème, mettez d’abord le déploiement en pause — arrête la nouvelle exposition pendant que vous investigatez. Les appareils déjà sur le build défectueux y restent jusqu’à ce que vous Rollback du déploiement ou Désactiver le déploiement progressif.

Déploiement complet vs Rollback vs Désactivation du déploiement

Terminer le déploiement lorsque le candidat est bon et doit devenir le fallback stable pour tous les appareils. Rollback du déploiement lorsque le candidat doit être abandonné et que tout le monde doit revenir au fallback stable précédent. Désactiver le déploiement progressif lorsque vous souhaitez arrêter le déploiement tout en conservant le même fallback stable sans finaliser le candidat.

Politique de pause automatique

Capgo peut évaluer un déploiement actif toutes les cinq minutes et agir lorsque son signal d’échec dépasse votre seuil. Il mesure les installations et les échecs pour la cible du déploiement dans le canal et la fenêtre de temps sélectionnés, puis utilise une borne inférieure de confiance de Wilson plutôt que le simple taux d’échec brut.

La pause automatique est désactivée par défaut. Configurez ces champs dans l’onglet du canal Informations ou avec channel set:

• Seuil du taux d’échec en points de base (500 = 5 %). Un seuil est nécessaire pour déclencher la politique.
• Fenêtre en minutes (par défaut : 60).
• Confiance entre 0 et 1 (par défaut : 0.95).
• Nombre minimal d’essais et d’échecs optionnel, pour éviter de réagir sur de trop petits échantillons.
• Délai d’attente en minutes (par défaut : 60), ce qui empêche les actions répétées.
• Action: pause, rollback, ou notify.

pause arrête l'exposition du nouveau déploiement progressif, rollback supprime la cible et revient à la version stable de secours, et notify envoie une alerte de déploiement sans modifier la diffusion du 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

Points d'entrée API et dashboard

• Dashboard : app → Canaux → canal → Informations → Déploiement progressif
• Canaux API : Canaux publics API pour les champs de rollout, promote et rollback
• Assignation du bundle API : PUT /bundle/ par target: auto, stable, ou rollout

Pour le routage général des canaux et la priorité des appareils, consultez Canaux. Pour une récupération d'urgence de bundle en dehors d'un déploiement progressif, consultez Effectuer un rollback d'un live update.