Capgo Pull Request Preview Cleanup API Key

Supprimer une prévisualisation de demande de tirage ressemble à un travail d'une commande. Avec CapgoEn supprimant une prévisualisation de demande de tirage, il y a un piège : il faut s'éloigner d'une prévisualisation active avant de la supprimer, puis supprimer ses lots par ID. Nous allons construire un flux de nettoyage sûr avec une clé API restreinte, recherche de prévisualisation, gestion de réinitialisation, suppression de lots et automatisation de CI.

Table des Matières

• Étape 1 : Créer une Clé Capgo API Restreinte pour la Prévisualisation de Nettoyage
• Étape 2 : Identifier la Prévisualisation de Demande de Tirage et ses Identifiants de Lots
• Étape 3 : Passer à une Prévisualisation Active Avant le Nettoyage
• Étape 4 : Supprimer les Lots de Prévisualisation par ID avec la Clé API
• Étape 5 : Automatiser le Nettoyage Lorsque une Demande de Tirage Se Ferme
• Étape 6 : Vérifier le Nettoyage et Protéger les Déploiements Contre la Suppression Accidentelle
• FAQ
• Conclusion

Étape 1 : Créez une clé restreinte Capgo API pour la prévisualisation de nettoyage.

The first step in a Capgo pull request preview cleanup flow is to make a key that can do only the work your CI job needs.

Ne mettez pas une clé d'organisation large dans un flux de demande de tirage. Une demande de tirage peut provenir d'une branche qui n'a pas encore gagné la confiance. Le flux peut également imprimer une commande ou une valeur d'environnement lors d'une exécution échouée. Une clé étroite limite les dommages si cela se produit.

Dans Capgo, commencez par une clé de prévisualisation d'application pour le travail de prévisualisation. La clé doit être liée à l'application ou à l'étendue de prévisualisation que votre job gère. Si votre équipe utilise un contrôle d'accès basé sur des rôles, limitez la clé aux applications sélectionnées au lieu de leur accorder accès à l'ensemble de l'organisation. Capgo documente ces choix de clés de prévisualisation dans son API key settings for web app workflows.

Stockez le secret dans le magasin de secrets chiffrés de votre fournisseur CI. Donnez-lui un nom qui indique ce qu'il fait, commeCAPGO_PREVIEW_CLEANUP_KEYN'insérez pas cela dans un fichier de flux de travail, un script shell, un commentaire de demande de tirage, ou un journal généré.

Transmettez la clé au processus de nettoyage à l'aide d'une variable d'environnement. Votre script doit échouer lorsque la variable est manquante. Un redoublement silencieux est dangereux car il peut transformer un job de nettoyage en une demande sans authentification, 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

Conservez cette clé à part de la clé utilisée pour publier des lots de production. Le job de publication peut avoir besoin d'uploader une version. Le job de nettoyage n'a besoin que de supprimer des ressources de prévisualisation. Des clés séparées facilitent la revue et réduisent la chance qu'une action de suppression atteigne un canal de production.

Utilisez le même secret dans un environnement protégé lorsque possible. Exigez une approbation avant que le job puisse toucher des canaux partagés. Pour les prévisualisations de requêtes de pull ordinaire, le job devrait fonctionner sur un canal temporaire et ne rien d'autre.

Retourne d'essence : Utilisez une clé de prévisualisation dédiée, restreignez son champ d'application et gardez-la dans des secrets CI chiffrés.

Avant de passer à l'étape suivante, testez la clé contre une action de lecture sans risque. Confirmez que le job peut voir l'application ciblée, mais ne peut pas accéder à une application non liée ou à un flux de production. Les détails exacts de la demande de nettoyage ne sont pas pleinement publiés, donc gardez votre premier test petit et inspectez la guidance de support SDK ou Capgo avant d'ajouter des appels de suppression.

Étape 2 : Identifiez la prévisualisation de requête de pull et ses identifiants de lot

The Capgo pull request preview cleanup API key is useful only when your job knows which preview and bundle IDs it owns.

La clé de nettoyage de la prévisualisation de requête de pull __CAPGO_KEEP_0__ est utile uniquement lorsque votre job connaît les identifiants de prévisualisation et de lot qu'il possède __CAPGO_KEEP_1__ .

Enregistrez le nom du canal de prévisualisation lors de la création de la prévisualisation. Vous pouvez le placer dans la sortie de flux, une vérification de demande de tirage, ou un petit morceau de métadonnées de travail. N'ayez pas confiance dans un nom de display que quelqu'un pourrait modifier dans le tableau de bord.

Listez ensuite les ensembles liés à cette prévisualisation. L'action de suppression de l'ensemble de Capgo nécessite des identifiants d'ensemble. La documentation source pointe vers une requête de liste pour récupérer tous les identifiants d'ensemble disponibles avant la suppression. Considérez cette liste comme la source de vérité. Ne jamais deviner un ID à partir d'un nom de fichier, d'un hachage de commit ou d'un nom de branch.

Filtrez les enregistrements retournés par le canal de prévisualisation ou une autre valeur que votre flux de travail contrôle. Gardez ensuite l'identifiant d'ensemble exact pour chaque correspondance. Si la liste est vide, marquez la suppression comme complète. Un résultat vide n'est pas un échec à moins que votre flux de travail ait attendu une prévisualisation.

Enregistrez également l'hachage de commit qui a produit chaque prévisualisation. Cela vous donne une deuxième vérification avant la suppression. Si le nom du canal correspond mais l'hachage de commit ne correspond pas, arrêtez-vous et demandez une revue. Cette petite pause peut prévenir une course où une nouvelle prévisualisation est en cours de construction tandis qu'un ancien job de suppression s'exécute.

N'effacez pas pendant qu'un job de publication est toujours en cours. Ajoutez une dépendance entre la construction de prévisualisation et les flux de travail de suppression, ou utilisez un verrou cléé sur le numéro de demande de tirage. Le job de suppression devrait démarrer uniquement après l'événement de fermeture et après que tout téléchargement de prévisualisation en attente ait pris fin.

Capgo’s public API couvre les ressources telles que les canaux et les ensembles à travers des requêtes HTTP authentifiées, mais les actions de nettoyage nécessitent encore une vérification soigneuse dans votre projet. Le Capgo public API d'ensemble est le bon endroit pour confirmer le modèle de ressources actuel avant de rédiger un wrapper.

À ce stade, vous devriez avoir un identifiant de prévisualisation, une liste d'IDs d'ensemble exacts et le SHA de commit lié à chaque enregistrement. Si l'un de ces valeurs manque, arrêtez-vous ici. Le nettoyage sans vérification d'appartenance est une supposition.

Étape 3 : Passer à une autre prévisualisation active avant le nettoyage

Une prévisualisation active ne peut pas être supprimée avant que l'application ne se déconnecte d'elle ou que vous appelezresetPreviewC'est le détail clé dans le flux de nettoyage de la prévisualisation de la demande de tirage de Capgo.

Think of the active preview as the version currently selected by the app. Deleting the server-side record first would leave the app pointing at something that no longer exists. Capgo blocks that state change, so your cleanup job must reset the app’s preview state before it removes the preview.

First, check whether the preview is still active. If it is, move the app to a safe channel or use the updater reset action. The right choice depends on how your test app is configured. A disposable test app can return to its normal default channel. A shared test app may need a dedicated staging channel instead.

UseresetPreviewLorsque l'état de prévisualisation doit être supprimé directement. Gardez cette appelle liée au même pull request et à l'application qui a créé la prévisualisation. Un script de nettoyage ne devrait jamais réinitialiser un appareil de production ou un canal de mise en production partagé simplement parce que le nom d'un canal correspond.

Il existe une règle d'ordre utile ici :

• Confirmez que le pull request est fermé.
• Confirm no preview upload is running.
• Poursuivez-vous de la prévisualisation active ou appelezresetPreview.
• Attendez que cet état de changement se termine.
• Appelez Delete Preview que lorsque vous êtes sûr.

N'interprétez pas une réponse HTTP réussie de la requête de réinitialisation comme preuve que l'application a déjà changé d'état sur chaque appareil. Un appareil peut vérifier les mises à jour plus tard. Votre serveur de nettoyage peut toujours se poursuivre une fois que l'affectation de prévisualisation a été supprimée selon la réponse API, mais gardez le comportement de l'appareil séparé de la suppression de ressources.

Capgo prend en charge le contrôle de la mise en production basé sur les canaux, ce qui rend cette séparation plus facile à raisonner. Un canal est un chemin nommé qui indique à une application quelle flux d'actualisation suivre. Votre canal de prévisualisation ne devrait jamais être le même canal utilisé par les appareils de production.

For teams that need a stricter boundary, use the documented flux de canal Capgo pour l'automatisation de la prévisualisationIl décrit le modèle de canal temporaire et aide à garder un job de nettoyage à l'écart des canaux par défaut partagés.

La documentation de l'actualiseur open-source enregistre également la limite de suppression : les prévisualisations actives nécessitent un déplacement ou un redémarrage avant. Vous pouvez examiner le code source dans le dépôt de l'actualiseur Capgo Capacitor. Ce code est utile lorsque les mots de la page de tableau de bord sont trop courts pour une décision CI.

Conseil Pro : Faites d'un reset une étape séparée. Si la suppression de la prévisualisation échoue, le journal doit montrer si la prévisualisation était toujours active ou si la demande de suppression avait un autre problème.

Une fois l'état actif disparu, le registre de la prévisualisation est prêt à la suppression. N'associez pas le reset et la suppression en une seule ligne opaque. Deux commandes claires sont plus faciles à réessayer et beaucoup plus faciles à auditer.

Étape 4 : Supprimer les Bundles de Prévisualisation par ID avec la clé API

Supprimez chaque bundle de prévisualisation par son ID exact, après que la prévisualisation active a été réinitialisée. C'est là où une clé de nettoyage Capgo supprime les objets de stockage laissés par la demande de pull.

Commencez par la liste des bundles de l'étape 2. Pour chaque ID correspondant, appelez l'action Supprimer le Bundle à travers la méthode Capgo SDK ou la méthode publique actuelle API disponible à votre compte.

Inspectez la signature de la méthode SDK ou confirmez la forme actuelle de la demande avec le support Capgo. Enregistrez la méthode et la forme de réponse dans le livre de route interne de votre équipe une fois que vous les avez vérifiées. Ce livre de route doit inclure la version API, l'identifiant requis et les codes d'erreur que votre logique de réessai peut gérer.

Utilisez un mode de simulation dans votre script. Il devrait imprimer le canal de prévisualisation et les identifiants de bundle qu'il supprimerait, sans envoyer de requêtes de suppression. Exécutez ce mode contre plusieurs demandes de tirage fermées. Vérifiez que cela exclut les canaux de production et qu'il ne traite pas une liste vide comme un joker.

Un boucle de suppression sécurisé a trois portes :

1. Rejetez un identifiant de bundle manquant ou mal formé.
2. Rejetez un bundle dont le canal ne correspond pas à la prévisualisation de la demande de tirage.
3. Supprimez uniquement après que le contrôle d'appartenance passe.

Traitez ensuite chaque réponse par type. Une suppression réussie peut être enregistrée comme complète. Une réponse non trouvée peut être traitée comme déjà propre si le ressource est connue pour avoir été supprimée par une tentative antérieure. Les erreurs d'autorisation doivent échouer la tâche et alerter le propriétaire. Les limites de taux doivent suspendre et réessayer avec un délai plafonné.

N'essayez pas de réessayer chaque erreur. Un mauvais ID ne deviendra pas valide après trois tentatives. Une erreur d'autorisation signifie généralement que le champ de portée de la clé est incorrect. Réessayez uniquement les échecs transitoires, et définissez un temps de course maximum pour qu'une tâche de nettoyage bloquée ne consomme pas votre file d'attente de CI.

La suppression de bundle est séparée de la suppression de prévisualisation. La suppression du canal de prévisualisation ne prouve pas automatiquement que tous les bundles ont disparu. Votre tâche doit conserver un résultat pour chaque ID, puis effectuer une requête finale si l’API le permet. Si un bundle reste, signalez l'ID et arrêtez plutôt que de prétendre à une réussite silencieuse.

Évitez les logs de suppression contenant des secrets. Il est acceptable de logger le numéro de demande de tirage, le nom de la prévisualisation, l'ID de l'ensemble, le résultat de la demande et la date. N'oubliez pas de ne pas logger la clé API, un en-tête d'autorisation ou un objet de demande complet qui pourrait inclure une clé.

Cet approche vous donne un utile journal d'audit sans transformer le journal en un autre endroit où les informations de connexion peuvent se répandre. Cela rend également une suppression échouée facile à reprendre car la prochaine exécution peut ignorer les enregistrements déjà confirmés comme absents.

Step 5: Automate Cleanup When a Pull Request Closes

Run the cleanup job from the pull request close event, but add checks that prevent a late build from deleting a new preview.

Votre workflow doit recevoir le nom du dépôt et le numéro de demande de tirage à partir du payload de l'événement. Reconstituez le nom du canal de prévisualisation à partir de ces valeurs. N'acceptez pas un nom de canal fourni par un commentaire de demande de tirage ou une variable de branch non fiable.

Une séquence d'opération utile ressemble à ceci :

1. Chargez la clé de suppression restreinte à partir de secrets chiffrés.
2. Confirmez que l'événement est une demande de tirage fermée.
3. Vérifiez que la prévisualisation appartient au dépôt et à l'application attendus.
4. Attendez que toute déploiement actif de prévisualisation se termine.
5. Éteignez la prévisualisation ou appelezresetPreview.
6. List bundle IDs for that preview.
7. Supprimer chaque bundle vérifié.
8. Supprimer l'enregistrement de prévisualisation.
9. Écrire un résultat court dans la synthèse du workflow.

Ordre important. Si vous supprimez d'abord, la règle de prévisualisation active peut bloquer la demande. Si vous passez par l'appel de liste, vous ne pourriez pas savoir quels ID de bundle existent encore. Si vous supprimez par un nom supposé, vous risquez de toucher le mauvais ressource.

Utiliser une règle de concurrence cléée sur le numéro de demande de tirage. Lorsqu'un événement de fermeture et un événement de reconstruction arrivent à peu près au même moment, l'ancien job de suppression ne doit pas courir le nouveau déploiement. Annuler une tâche de suppression obsolète ou faire attendre le job jusqu'à ce que le verrou de déploiement soit libéré.

Capgo’s flux de travail CLI en une commande peut réduire le nombre de appels de shell personnalisés autour de la construction et de la mise en production. Pour les noms de commandes et les opérations prises en charge, consultez la Capgo documentation de commande CLI. Utilisez le CLI où cela vous donne une commande vérifiée. Utilisez le SDK ou l’API public où les actions de suppression nécessitent une demande directe.

Ne mettez pas la suppression dans un flux de travail qui s'exécute avec chaque push. Un job de push peut supprimer une prévisualisation qui est toujours en cours de test. L'événement de fermeture est le déclencheur approprié pour la suppression normale. Ajoutez un flux de travail de déclenchement manuel pour la récupération lorsqu'un job fail.

Set a retention fallback too. If a close event is missed, a scheduled job can find previews older than your team’s allowed test window. That job needs stricter safeguards than the normal close hook. It should select only previews with a clear owner and an expired timestamp.

For GitHub Actions, keep permissions narrow and pass only the values needed by the cleanup step. Capgo’s current GitHub Actions integration documentation explains where the token is stored and how the workflow connects to Capgo.

Vous devriez maintenant avoir un chemin automatisé qui réagit à la fermeture, attend les tâches concurrentes, réinitialise l'état actif, affiche les ID et supprime uniquement les ensembles de bundles correspondants.

Étape 6 : Vérifiez le nettoyage et protégez les déploiements contre la suppression accidentelle.

La vérification ferme le Capgo boucle de nettoyage de la prévisualisation de la demande de tirage.

After the cleanup job runs, check the preview channel again. Confirm that it no longer appears as an active preview. Then check the bundle list for the same app and filter. The expected result is that the targeted bundle IDs are gone while production bundles remain.

Enregistrez ces valeurs dans le résumé de la tâche :

• Répertoire et numéro de demande de tirage.
• Nom de canal de prévisualisation.
• Nom du canal de prévisualisation.
• IDs de bundle trouvés.
• ID des ensembles trouvés.
• ID des ensembles supprimés.

Utilisez un statut clair. « Nettoyé » signifie que tous les cibles vérifiées sont supprimées. « Déjà propre » signifie que la ressource n'était pas présente avant cette exécution. « Besoin de revue » signifie que l'une ou plusieurs vérifications ont échoué. N'étiquetez pas une suppression partielle en tant que succès.

Ajoutez un garde de production dans code. Rejetez les noms de canal comme votre canal par défaut ou votre canal de mise en production. Rejetez également un bundle si son métadonnée ne correspond pas à l'application de prévisualisation. Le garde devrait échouer fermé. Lorsque le script ne peut pas identifier la cible avec confiance, il devrait s'arrêter.

Conservez le rollback séparé du nettoyage. Un rollback change le bundle que les appareils reçoivent. Le nettoyage supprime une ancienne ressource de prévisualisation. Si un test trouve un bug après que la demande de tirage est fermée, vous pourriez avoir besoin du bundle pour l'investigation. Définissez une fenêtre de conservation courte au lieu de supprimer instantanément l'événement si votre équipe débogue souvent après la fusion.

Surveillez trois modèles de failure courants :

• Erreur de prévisualisation active : Réinitialiser ou passer à autre chose avant de réessayer Supprimer l'avance.
• ID de bundle manquant : exécutez l'action de liste à nouveau au lieu de deviner.
• Erreur de permission : examinez l'étendue de la clé, puis émettez une nouvelle clé si nécessaire.

Rotez la clé de nettoyage à un horaire défini par votre politique de sécurité, et rotez-l’immédiatement si elle apparaît dans un journal ou un commit. Une nouvelle clé devrait être testée avant que l'ancienne ne soit révoquée, à moins que l'exposition nécessite une révocation immédiate.

La documentation manquante autour de la suppression mérite une note dans votre revue de sécurité. Traitez les SDK et les Capgo conseils vérifiés comme source pour votre mise en œuvre, et gardez votre propre contrat de demande sous contrôle de version.

Preuve clé : Vérifiez la prévisualisation et la liste de packages après suppression, bloque les cibles de production dans code et signalez une suppression partielle comme un échec.

Une seule commande est utile uniquement lorsque les garde-fous sont clairs. Suivez la prévisualisation. Adoptez un nom de canal prévisible. Annulez les modifications de publication séparément. Ensuite, laissez le travail de suppression faire son petit travail sans toucher le trafic en direct.

FAQ

Peut-on supprimer une prévisualisation active Capgo ?

Non. Une prévisualisation active doit être déplacée d'abord, ou vous devez appeler resetPreviewAprès que l'état actif est clair, exécutez Supprimer la prévisualisation. Cette règle est le détail principal à retenir lors de la configuration d'une clé de suppression de prévisualisation Capgo de demande de tirage API dans CI.

Faut-il des identifiants de bundle pour nettoyer une Capgo prévision ?

Oui. L'action Supprimer le bundle de Capgo nécessite les identifiants de bundle, donc listez les bundles disponibles avant de les supprimer. Correspondez chaque ID à la chaîne de canal de prévisualisation et au commit avant d'envoyer une demande de suppression. N'édifiez jamais un ID à partir d'un nom de branche ou supposez que la suppression de la prévisualisation supprime également tous les bundles.

Quel type de clé API devrait utiliser CI pour la suppression de prévisualisation ?

Utilisez une clé de prévisualisation d'application restreinte pour la mise à jour de la prévisualisation, stockée dans le magasin de secrets chiffrés de votre fournisseur CI. Limitez la clé à l'application ou à l'étendue dont elle a besoin. Gardez-la séparée de la clé utilisée pour publier les mises à jour de production. Cela rend la tâche de nettoyage Capgo plus facile à examiner et plus sûre à mettre à jour.

Peut-on automatiser la mise à jour lorsque la demande de tirage se ferme ?

Yes. Trigger cleanup from the closed pull request event, then wait for active deployment jobs before resetting the preview. List the bundle IDs, delete verified matches, and confirm the result. Add concurrency controls so a late build cannot race the cleanup job.

Pourquoi ma demande de nettoyage Capgo échoue-t-elle ?

Les causes habituelles sont une prévisualisation active, un identifiant de bundle manquant ou une clé sans l'étendue nécessaire. Réinitialisez la prévisualisation d'abord, répétez l'appel de liste, puis inspectez les permissions de la clé. Puisque les détails de la demande peuvent varier en fonction de la version API ou SDK, confirmez la méthode actuelle et les paramètres avant de modifier le script.

Conclusion

Utilisez Capgo avec une clé de prévisualisation dédiée et un ordre de nettoyage strict : réinitialisez la prévisualisation active, listez ses identifiants de bundle, supprimez les bundles vérifiés, puis supprimez la prévisualisation. Commencez par une mise en œuvre sèche contre une demande de tirage fermée, confirmez la forme de la demande dans la version actuelle SDK, et ajoutez la garde de canal de production avant d'activer la mise à jour automatique.