Clé API Capgo pour nettoyer les previews de pull request

Supprimer une preview de pull request semble ne demander qu'une commande. Avec ça Capgo, il y a un piège : vous devez quitter une preview active avant de la supprimer, puis retirer ses bundles par ID. Nous allons mettre en place un flux de nettoyage sécurisé avec une clé API restreinte, la recherche de preview, la gestion de la réinitialisation, la suppression de bundles et l'automatisation CI.

Table des matières

• Étape 1 : créer une clé API Capgo restreinte pour le nettoyage des previews
• Étape 2 : identifier la preview de pull request et ses ID de bundles
• Étape 3 : Quitter l'aperçu actif avant le nettoyage
• Étape 4 : Supprimer les bundles de preview par ID avec la clé API
• Étape 5 : Automatiser le nettoyage lors de la fermeture d'une pull request
• Étape 6 : vérifier le nettoyage et protéger les déploiements contre une suppression accidentelle
• FAQ
• Conclusion

Étape 1 : créer une clé API Capgo restreinte pour le nettoyage des previews

La première étape d'un flux de nettoyage des previews de pull request Capgo consiste à créer une clé capable d'effectuer uniquement les tâches nécessaires à votre job CI.

N'utilisez pas une clé d'organisation étendue dans un workflow de pull request. Une pull request peut provenir d'une branche qui n'a pas encore fait ses preuves. Le workflow peut aussi afficher une commande ou une valeur d'environnement lors d'une exécution échouée. Une clé restreinte limite les dégâts si cela se produit.

Dans Capgo, commencez par une clé App Preview pour le travail de preview. La clé doit être liée à l'application ou au scope de preview que votre job gère. Si votre équipe utilise le contrôle d'accès basé sur les rôles, limitez la clé à des apps sélectionnées plutôt que d'accorder un accès à toute l'organisation. Capgo documente ces choix de clés de preview dans sa API : paramètres de clé pour les workflows d'app web.

Stockez le secret dans le gestionnaire de secrets chiffrés de votre fournisseur CI. Donnez-lui un nom explicite, par exempleCAPGO_PREVIEW_CLEANUP_KEYNe l'insérez pas dans un fichier de workflow, un script shell, un commentaire de pull request ou un log généré.

Passez la clé au processus de cleanup via une variable d'environnement. Votre script doit échouer si la variable est manquante. Un fallback silencieux est dangereux, car il peut transformer un job de cleanup en une requête sans auth, ou inciter un développeur à coller une clé dans la ligne de commande.

if [ -z "$CAPGO_PREVIEW_CLEANUP_KEY" ]; then echo "Missing preview cleanup key" exit 1
fi

Gardez cette clé séparée de celle utilisée pour publier les bundles de production. Le job de publication peut avoir besoin d'envoyer une release. Le job de cleanup doit uniquement supprimer les ressources de preview. Des clés distinctes facilitent la revue et réduisent le risque qu'une action de suppression atteigne un canal de production.

Utilisez le même secret dans un environnement protégé lorsque cela est possible. Exigez une approbation avant qu'un job ne puisse toucher aux canaux partagés. Pour les previews de pull request classiques, le job doit se limiter à un canal temporaire.

À retenir : Utilisez une clé App Preview dédiée, limitez son scope à l'application, et conservez-la dans les secrets chiffrés de votre CI.

Avant de continuer, testez la clé avec une action de lecture inoffensive. Confirmez que le job peut voir l'application prévue, mais ne peut pas accéder à une application sans rapport ni à un workflow de production. Les détails exacts des requêtes de cleanup ne sont pas entièrement publiés, alors limitez votre premier test et consultez les recommandations du support SDK ou Capgo avant d'ajouter des appels de suppression.

Étape 2 : identifier la preview de pull request et ses ID de bundles

La clé API de nettoyage des previews de pull request Capgo n'est utile que si votre job connaît les IDs de preview et de bundle dont il est responsable.

Utilisez une règle de nommage stable pour les canaux de preview. Un schéma courant consiste à associer le nom du dépôt au numéro de pull request. L’essentiel est la cohérence : votre tâche de nettoyage doit reconstruire exactement le même identifiant après la fermeture de la pull request.

Enregistrez le nom du canal de preview lors de sa création. Vous pouvez le placer dans la sortie du workflow, dans une vérification de pull request ou dans une petite métadonnée de job. Ne vous fiez pas à un nom d’affichage qu’une personne pourrait modifier dans le dashboard.

Ensuite, listez les bundles liés à cette preview. L’action Delete Bundle de Capgo nécessite des identifiants de bundle. La documentation source renvoie vers un appel de liste pour récupérer tous les identifiants de bundle disponibles avant suppression. Considérez cette liste comme la source de vérité. Ne devinez jamais un identifiant à partir d’un nom de fichier, d’un hash de commit ou d’un nom de branche.

Filtrez les enregistrements retournés par le canal de preview ou une autre valeur contrôlée par votre workflow. Conservez ensuite l’identifiant de bundle exact pour chaque correspondance. Si la liste est vide, marquez le nettoyage comme terminé. Un résultat vide n’est pas une erreur, sauf si votre workflow s’attendait à l’existence d’une preview.

Enregistrez également le SHA du commit ayant généré chaque preview. Cela vous donne une seconde vérification avant suppression. Si le nom du canal correspond mais que le commit ne correspond pas, arrêtez-vous et demandez une revue. Cette petite pause peut éviter une course où une nouvelle preview est en cours de build pendant qu’un ancien job de nettoyage s’exécute.

Ne supprimez rien tant qu'un job de publication est en cours. Ajoutez une dépendance entre le workflow de build de preview et celui de cleanup, ou utilisez un verrou basé sur le numéro de la pull request. Le job de cleanup ne doit démarrer qu'après l'événement de fermeture et une fois que tout upload de preview en attente est terminé.

L'API publique de Capgo couvre les ressources telles que les canaux et les bundles via des requêtes HTTP authentifiées, mais les actions de cleanup nécessitent tout de même une vérification minutieuse dans votre projet. L' aperçu de l'API publique de Capgo est l'endroit idéal pour confirmer le modèle de ressources actuel avant d'écrire un wrapper.

À ce stade, vous devriez avoir un identifiant de preview, une liste d'ID de bundles exacts et le SHA du commit lié à chaque enregistrement. Si l'une de ces valeurs manque, arrêtez-vous là. Un cleanup sans vérification de propriété relève de la devinette.

Étape 3 : Quitter l'aperçu actif avant le nettoyage

Une preview active ne peut pas être supprimée tant que l'app ne l'a pas quittée ou que vous n'avez pas appeléresetPreview. C'est le détail clé du flux de cleanup des previews de pull request de Capgo.

Considérez la preview active comme la version actuellement sélectionnée par l'app. Supprimer l'enregistrement côté serveur en premier laisserait l'app pointer vers quelque chose qui n'existe plus. Capgo bloque ce changement d'état, votre job de cleanup doit donc réinitialiser l'état de preview de l'app avant de supprimer la preview.

Tout d'abord, vérifiez si la preview est toujours active. Si c'est le cas, déplacez l'app vers un canal sûr ou utilisez l'action de reset de l'updater. Le bon choix dépend de la configuration de votre app de test. Une app de test jetable peut revenir à son canal par défaut, tandis qu'une app de test partagée pourrait nécessiter un canal de staging dédié.

UtiliserresetPreviewlorsque l'état de la preview doit être effacé directement. Liez cet appel à la même pull request et à la même app que celles ayant créé la preview. Un script de cleanup ne doit jamais réinitialiser un appareil de production ou un canal de release partagé simplement parce que le nom d'un canal correspond.

Voici une règle d'ordre utile :

• Confirmez que la pull request est fermée.
• Confirmez qu'aucun upload de preview n'est en cours.
• Quittez la preview active ou appelezresetPreview.
• Attendez la fin de ce changement d'état.
• N'appelez Delete Preview qu'ensuite.

Ne considérez pas une réponse HTTP réussie à la requête de reset comme preuve que l'app a déjà changé d'état sur chaque appareil. Un appareil peut vérifier les mises à jour plus tard. Votre cleanup côté serveur peut continuer une fois l'affectation de la preview effacée d'après la réponse API, mais gardez le comportement de l'appareil distinct de la suppression des ressources.

Capgo prend en charge le contrôle du déploiement progressif par canal, ce qui rend cette séparation plus facile à appréhender. Un canal est un chemin nommé qui indique à une app quel flux de mise à jour suivre. Votre canal de preview ne doit jamais être celui utilisé par les appareils de production.

Pour les équipes nécessitant une limite plus stricte, utilisez la solution documentée Workflow Capgo pour l’automatisation des previews. Il décrit le motif de canal temporaire et aide à isoler la tâche de nettoyage des canaux par défaut partagés.

La documentation de l’updater open source documente également la limite de suppression : les previews actives nécessitent d’abord un changement d’état ou un reset. Vous pouvez consulter le code source dans le dépôt Capgo Capacitor updater. Cette source est utile lorsque la formulation du dashboard est trop concise pour une décision CI.

Conseil de pro : Faites du reset une étape distincte et journalisée. Si Delete Preview échoue, les logs doivent indiquer si la preview était encore active ou si la requête de suppression a rencontré un autre problème.

Une fois l’état actif supprimé, l’enregistrement de la preview est prêt pour la suppression. Ne combinez pas reset et delete en une seule ligne shell opaque. Deux commandes claires sont plus faciles à réessayer et beaucoup plus simples à auditer.

Étape 4 : Supprimer les bundles de preview par ID avec la clé API

Supprimez chaque bundle de preview par son ID exact, après le reset de la preview active. C’est ici qu’une clé de nettoyage Capgo supprime les objets de stockage laissés par la pull request.

Commencez par la liste des bundles de l’étape 2. Pour chaque ID correspondant, appelez l’action Delete Bundle via Capgo SDK ou la méthode publique API actuelle disponible pour votre compte.

Inspectez la signature de la méthode SDK ou confirmez la forme de la requête actuelle avec le support Capgo. Enregistrez la méthode et le format de réponse dans le runbook interne de votre équipe une fois vérifiés. Ce runbook doit inclure la version API, l’identifiant requis et les codes d’erreur que votre logique de retry peut gérer.

Utilisez un mode dry-run dans votre script. Il doit afficher le canal de preview et les IDs de bundle qui seraient supprimés, sans envoyer de requêtes de suppression. Exécutez ce mode sur plusieurs pull requests fermées. Vérifiez qu’il exclut les canaux de production et qu’il ne traite pas une liste vide comme un joker.

A safe deletion loop has three gates:

1. Rejeter un ID de bundle manquant ou mal formé.
2. Rejeter un bundle dont le canal ne correspond pas à l’aperçu de la pull request.
3. Supprimer uniquement après le passage du contrôle de propriété.

Ensuite, traitez chaque réponse par type. Une suppression réussie peut être marquée comme terminée. Une réponse « introuvable » peut être considérée comme propre si la ressource a déjà été supprimée par une tentative antérieure. Les erreurs de permission doivent faire échouer le job et alerter le propriétaire. Les limites de débit doivent mettre en pause et réessayer avec un délai plafonné.

Ne réessayez pas toutes les erreurs. Un ID invalide ne deviendra pas valide après trois tentatives. Une erreur d’autorisation signifie généralement que le périmètre de la clé est incorrect. Réessayez uniquement les échecs transitoires et définissez une durée d’exécution maximale pour qu’un job de nettoyage bloqué ne consomme pas votre file CI.

La suppression des bundles est distincte de la suppression des previews. Supprimer le canal de preview ne prouve pas automatiquement que tous les bundles ont disparu. Votre job doit conserver un résultat pour chaque ID, puis effectuer une requête de liste finale si API le permet. Si un bundle subsiste, signalez l’ID et arrêtez-vous plutôt que de prétendre au succès en silence.

Gardez les logs de suppression exempts de secrets. Il est acceptable de journaliser le numéro de pull request, le nom du preview, l'ID du bundle, le résultat de la requête et l'horodatage. Ne journalisez jamais la clé API, un en-tête d'autorisation ou un objet de requête complet qui pourrait en contenir un.

Cette approche vous offre une piste d'audit utile sans transformer le log en un autre endroit où les identifiants peuvent fuiter. Elle facilite également la reprise d'un nettoyage échoué, car l'exécution suivante peut ignorer les enregistrements déjà confirmés comme absents.

Étape 5 : Automatiser le nettoyage lors de la fermeture d'une pull request

Lancez le job de nettoyage à la fermeture de la pull request, mais ajoutez des vérifications pour empêcher un build tardif de supprimer un nouveau preview.

Votre workflow doit recevoir le dépôt et le numéro de pull request depuis la charge utile de l'événement. Reconstruisez le nom du canal de preview à partir de ces valeurs. N'acceptez pas un nom de canal fourni par un commentaire de pull request ou une variable de branche non fiable.

Une séquence de job utile ressemble à ceci :

1. Chargez la clé de nettoyage restreinte depuis les secrets chiffrés.
2. Confirmez que l'événement est une pull request fermée.
3. Vérifiez que le preview appartient au dépôt et à l'application attendus.
4. Attendez la fin de tout déploiement de preview actif.
5. Basculez hors du preview ou appelezresetPreview.
6. Lister les IDs de bundle pour cet aperçu.
7. Supprimer chaque bundle vérifié.
8. Supprimer l'enregistrement de l'aperçu.
9. Écrire un court résultat dans le résumé du workflow.

L'ordre compte. Si vous supprimez d'abord, la règle d'aperçu active peut bloquer la requête. Si vous omettez l'appel de liste, vous ne saurez peut-être pas quels IDs de bundle existent encore. Si vous supprimez d'après un nom deviné, vous risquez de toucher la mauvaise ressource.

Utilisez une règle de concurrence basée sur le numéro de la pull request. Lorsqu'un événement de fermeture et un événement de rebuild arrivent presque en même temps, l'ancien job de nettoyage ne doit pas entrer en conflit avec le nouveau déploiement. Annulez une exécution de nettoyage obsolète ou faites attendre le job jusqu'à ce que le verrou de déploiement soit libéré.

Le workflow CLI en une commande de Capgo peut réduire le nombre d'appels shell personnalisés autour du build et de la release. Pour les noms de commandes et les opérations prises en charge, consultez la documentation de la commande CLI de Capgo. Utilisez CLI lorsqu'il fournit une commande vérifiée. Utilisez SDK ou l'API publique lorsque les actions de nettoyage nécessitent une requête directe.

Ne placez pas le nettoyage dans un workflow qui s'exécute à chaque push. Un job de push peut supprimer un aperçu encore en cours de test. L'événement de fermeture est le bon déclencheur pour un nettoyage normal. Ajoutez un workflow dispatch manuel pour la reprise en cas d'échec d'un job.

Prévoyez aussi un fallback de rétention. Si un événement de fermeture est manqué, une tâche planifiée peut retrouver les previews plus anciennes que la fenêtre de test autorisée par votre équipe. Cette tâche a besoin de garde-fous plus stricts que le hook de fermeture habituel. Elle ne doit sélectionner que les previews avec un propriétaire bien identifié et un timestamp expiré.

Pour les GitHub Actions, limitez la portée des permissions et ne transmettez que les valeurs dont l'étape de nettoyage a besoin. La documentation actuelle de l'intégration GitHub Actions de Capgo explique où le token est stocké et comment le workflow se connecte à Capgo.

À ce stade, vous devriez avoir un mécanisme automatisé qui réagit à la fermeture, attend les jobs concurrents, réinitialise l'état actif, liste les IDs et ne supprime que les bundles correspondants. C'est assez rapide pour le développement quotidien sans transformer le nettoyage en balayage à l'aveugle.

Étape 6 : vérifier le nettoyage et protéger les déploiements contre une suppression accidentelle

Verification ferme la boucle de nettoyage des previews de pull request Capgo. Une simple réponse de suppression ne suffit pas pour un processus de release sécurisé.

Une fois le job de nettoyage terminé, vérifiez à nouveau le canal de preview. Confirmez qu'il n'apparaît plus comme une preview active. Ensuite, consultez la liste des bundles pour la même application et le même filtre. Le résultat attendu est que les IDs des bundles ciblés aient disparu tandis que les bundles de production restent.

Enregistrez ces valeurs dans le résumé du job :

• Dépôt et numéro de la pull request.
• Nom du canal de preview.
• Commit SHA used for ownership checks.
• IDs de bundles trouvés.
• IDs de bundles supprimés.
• Tous les IDs ayant renvoyé une erreur.

Utilisez un statut clair. « Cleaned » signifie que toutes les cibles vérifiées ont été supprimées. « Already clean » signifie que la ressource était absente avant cette exécution. « Needs review » signifie qu’une ou plusieurs vérifications ont échoué. Ne qualifiez jamais une suppression partielle de succès.

Ajoutez une garde de production dans code. Rejetez les noms de canaux tels que votre canal par défaut ou de release. Rejetez également un bundle si ses métadonnées ne correspondent pas à l’application de preview. La garde doit échouer de manière sécurisée. Si le script ne peut pas identifier la cible avec certitude, il doit s’arrêter.

Gardez le rollback séparé du nettoyage. Un rollback modifie le bundle reçu par les appareils. Le nettoyage supprime une ressource de preview obsolète. Si un test révèl’un bug après la fermeture de la pull request, vous pourriez avoir besoin du bundle pour l’investigation. Définissez une fenêtre de rétention courte plutôt que de supprimer immédiatement à l’arrivée de l’événement si votre équipe débogue souvent après le merge.

Vigilance sur trois motifs d’échec courants :

• Erreur de preview active : réinitialisez ou basculez avant de réessayer Delete Preview.
• Bundle ID manquant : relancez l’action list plutôt que de deviner.
• Erreur de permission : vérifiez le périmètre de la clé, puis émettez une nouvelle clé si nécessaire.

Faites tourner la clé de nettoyage selon l’échancier défini par votre politique de sécurité, et immédiatement si elle apparaît dans un log ou un commit. Une nouvelle clé doit être testée avant la révocation de l’ancienne, sauf si l’exposition exige une révocation immédiate.

Le manque de documentation autour du nettoyage mérite une mention dans votre revue de sécurité. Considérez la documentation SDK et les consignes vérifiées Capgo comme la source de votre implémentation, et gardez votre propre contrat de requête sous gestion de version.

À retenir : Vérifiez la liste des previews et des bundles après suppression, bloquez les cibles de production dans code et signalez un nettoyage partiel comme un échec.

Une seule commande n’est utile que si les garde-fous sont clairs. Suivez la preview. Adoptez un nom de canal prévisible. Faites un rollback des changements de release séparément. Laissez ensuite le job de nettoyage faire son travail sans impacter le trafic live.

FAQ

Puis-je supprimer une preview de pull request Capgo active ?

Non. Il faut d’abord désactiver la preview active, ou appelerresetPreview. Une fois l’état actif levé, exécutez Delete Preview. C’est le point clé à retenir lors de la configuration d’une clé API de nettoyage des previews de pull request Capgo en CI.

Ai-je besoin des bundle IDs pour nettoyer une preview Capgo ?

Oui. L’action Delete Bundle de Capgo exige les bundle IDs, donc listez les bundles disponibles avant de les supprimer. Associez chaque ID au canal de preview et au commit avant d’envoyer une requête de suppression. Ne construisez jamais un ID à partir d’un nom de branche et ne supposez pas que la suppression de la preview supprime aussi tous les bundles.

Quel type de clé API la CI doit-elle utiliser pour le nettoyage des previews ?

Utilisez une clé App Preview restreinte pour le nettoyage des previews, stockée dans le coffre-fort de secrets chiffrés de votre fournisseur CI. Limitez la clé à l’app ou au périmètre nécessaire. Gardez-la distincte de la clé utilisée pour publier les mises à jour de production. Cela facilite la revue du job de nettoyage Capgo et rend sa rotation plus sûre.

Puis-je automatiser le nettoyage lors de la fermeture d'une pull request ?

Oui. Déclenchez le nettoyage à partir de l’événement de fermeture de la pull request, puis attendez la fin des jobs de déploiement actifs avant de réinitialiser la preview. Listez les bundle IDs, supprimez les correspondances vérifiées et confirmez le résultat. Ajoutez des contrôles de concurrence pour qu’un build tardif ne crée pas de course avec le job de nettoyage.

Pourquoi ma requête de nettoyage Capgo échoue-t-elle ?

Les causes habituelles sont une preview active, un bundle ID manquant ou une clé sans le périmètre requis. Réinitialisez d’abord la preview, répétez l’appel de liste et inspectez les permissions de la clé. Comme les détails des requêtes peuvent varier selon la version de API ou de SDK, vérifiez la méthode et les paramètres actuels avant de modifier le script.

Conclusion

Utilisez Capgo avec une clé preview dédiée et un ordre de nettoyage strict : réinitialisez la preview active, listez ses bundle IDs, supprimez les bundles vérifiés, puis retirez la preview. Commencez par un dry run sur une pull request fermée, confirmez la forme de la requête dans la version actuelle de SDK, et ajoutez la garde du canal de production avant d’activer le nettoyage automatique.