Capgo Pull-Request-Preview-Cleanup API Key

Das Löschen einer Pull-Request-Preview wirkt wie ein Ein-Befehl-Job. Dabei Capgogibt es einen Haken: Du musst eine aktive Preview verlassen, bevor du sie löschst, und anschließend ihre Bundles per ID entfernen. Wir bauen einen sicheren Cleanup-Flow mit einem eingeschränkten API Key, Preview-Lookup, Reset-Handling, Bundle-Löschung und CI-Automatisierung.

Inhaltsverzeichnis

• Schritt 1: Einen eingeschränkten Capgo API Key für das Preview Cleanup erstellen
• Schritt 2: Pull Request Preview und die zugehörigen Bundle IDs identifizieren
• Schritt 3: Vor dem Cleanup von der aktiven Preview wegwechseln
• Schritt 4: Preview-Bundles per ID mit dem API Key löschen
• Schritt 5: Cleanup automatisieren, wenn ein Pull Request geschlossen wird
• Schritt 6: Cleanup verifizieren und Rollouts vor versehentlichem Löschen schützen
• FAQ
• Fazit

Schritt 1: Einen eingeschränkten Capgo API Key für das Preview Cleanup erstellen

Der erste Schritt in einem Capgo Pull-Request-Preview-Cleanup-Flow ist, einen Key zu erstellen, der nur die Arbeit erledigen kann, die dein CI-Job braucht.

Verwende keinen breit gefassten Organisations-Key in einem Pull-Request-Workflow. Ein Pull Request kann von einem Branch kommen, dem noch nicht vertraut werden kann. Zudem könnte der Workflow bei einem fehlgeschlagenen Run einen Befehl oder einen Environment-Wert ausgeben. Ein eng gefasster Key begrenzt den Schaden, falls das passiert.

Beginne in Capgo mit einem App Preview Key für Preview-Aufgaben. Der Key sollte an den App- oder Preview-Scope gebunden sein, den dein Job verwaltet. Wenn dein Team Role-Based Access Control nutzt, beschränke den Key auf ausgewählte Apps, anstatt Zugriff auf die gesamte Organisation zu gewähren. Capgo dokumentiert diese Entscheidungen für Preview Keys in seinen API Key-Einstellungen für Web-App-Workflows.

Speichere das Secret im verschlüsselten Secret Store deines CI-Providers. Gib ihm einen Namen, der beschreibt, was es tut, wie zum BeispielCAPGO_PREVIEW_CLEANUP_KEY. Platziere es nicht in einer Workflow-Datei, einem Shell-Skript, einem Pull-Request-Kommentar oder einem generierten Log.

Übergib den Key für den Cleanup-Prozess über eine Umgebungsvariable. Dein Skript sollte fehlschlagen, wenn die Variable fehlt. Ein stiller Fallback ist gefährlich: Er kann einen Cleanup-Job in eine Anfrage ohne Auth verwandeln oder einen Entwickler dazu verleiten, einen Key in die Kommandozeile zu kopieren.

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

Halte diesen Key getrennt von dem Key, der zum Veröffentlichen von Production-Bundles genutzt wird. Der Publish-Job muss eventuell ein Release hochladen. Der Cleanup-Job muss lediglich Preview-Ressourcen entfernen. Getrennte Keys erleichtern das Review und verringern das Risiko, dass eine Löschaktion einen Production-Channel erreicht.

Nutze nach Möglichkeit dasselbe Secret in einer geschützten Umgebung. Fordere eine Freigabe an, bevor ein Job auf gemeinsame Channels zugreifen darf. Für normale Pull-Request-Previews sollte der Job ausschließlich auf einem temporären Channel arbeiten.

Das Wichtigste in Kürze: Nutze einen dedizierten App Preview Key, schränke dessen App-Scope ein und speichere ihn in verschlüsselten CI-Secrets.

Bevor du weitermachst, teste den Key mit einer harmlosen Read-Aktion. Bestätige, dass der Job die vorgesehene App sieht, aber nicht auf eine andere App oder einen Production-Workflow zugreifen kann. Da die genauen Request-Details für den Cleanup noch nicht vollständig veröffentlicht sind, halte deinen ersten Test klein und prüfe die SDK oder Capgo Support-Hinweise, bevor du Delete-Aufrufe hinzufügst.

Schritt 2: Pull Request Preview und die zugehörigen Bundle IDs identifizieren

Der Capgo Pull-Request-Preview-Cleanup API Key ist nur dann nützlich, wenn dein Job weiß, welche Preview- und Bundle-IDs ihm gehören.

Verwende eine stabile Namensregel für Preview-Channels. Ein gängiges Muster ist Repository-Name plus Pull-Request-Nummer. Entscheidend ist die Konsistenz. Dein Cleanup-Job muss nach dem Schließen des Pull Requests dieselbe Kennung erneut erzeugen.

Speichere den Preview-Channel-Namen, wenn die Preview erstellt wird. Du kannst ihn im Workflow-Output, in einem Pull-Request-Check oder in ein paar Job-Metadaten ablegen. Verlasse dich nicht auf einen Anzeigenamen, den jemand im Dashboard ändern könnte.

Liste als Nächstes die Bundles auf, die mit dieser Preview verknüpft sind. Die Delete-Bundle-Aktion von Capgo erfordert Bundle-IDs. Die Dokumentation verweist auf einen List-Call, um vor dem Löschen alle verfügbaren Bundle-IDs abzurufen. Behandle diese Liste als Source of Truth. Errate niemals eine ID aus einem Dateinamen, Commit-Hash oder Branch-Namen.

Filtere die zurückgegebenen Datensätze nach dem Preview-Channel oder einem anderen Wert, den dein Workflow steuert. Behalte dann die exakte Bundle-ID für jeden Treffer bei. Ist die Liste leer, markiere das Cleanup als abgeschlossen. Ein leeres Ergebnis ist kein Fehler, es sei denn, dein Workflow erwartete, dass eine Preview existiert.

Halte auch den Commit-SHA fest, der die jeweilige Preview erzeugt hat. Das gibt dir eine zweite Prüfung vor der Löschung. Wenn der Channel-Name übereinstimmt, der Commit aber nicht, halte an und bitte um Review. Diese kurze Pause kann eine Race Condition verhindern, bei der eine neue Preview gebaut wird, während ein alter Cleanup-Job läuft.

Lösche nicht, während ein Publish-Job noch läuft. Füge eine Abhängigkeit zwischen den Workflows für Preview-Build und Cleanup hinzu oder nutze ein Lock, das an die Pull-Request-Nummer gebunden ist. Der Cleanup-Job sollte erst nach dem Close-Event und nach Abschluss eines ausstehenden Preview-Uploads starten.

Die öffentliche API von Capgo deckt Ressourcen wie Channels und Bundles über authentifizierte HTTP-Anfragen ab, aber die Cleanup-Aktionen erfordern in Ihrem Projekt noch sorgfältige Verifikation. Die Übersicht der öffentlichen API von Capgo ist der richtige Ort, um das aktuelle Ressourcenmodell zu bestätigen, bevor Sie einen Wrapper schreiben.

Zu diesem Zeitpunkt sollten Sie einen Preview-Identifier, eine Liste exakter Bundle-IDs und die Commit-SHA, die mit jedem Datensatz verknüpft ist, haben. Wenn einer dieser Werte fehlt, stoppen Sie hier. Cleanup ohne Ownership-Checks ist reine Spekulation.

Schritt 3: Vor dem Cleanup von der aktiven Preview wegwechseln

Eine aktive Preview kann nicht gelöscht werden, bis die App von ihr wegschaltet oder SieresetPreview. Dies ist das entscheidende Detail im Capgo-Pull-Request-Preview-Cleanup-Flow.

Betrachten Sie die aktive Preview als die Version, die aktuell von der App ausgewählt ist. Würde man zuerst den serverseitigen Datensatz löschen, würde die App auf etwas zeigen, das nicht mehr existiert. Capgo blockiert diesen Zustandswechsel, daher muss Ihr Cleanup-Job den Preview-Zustand der App zurücksetzen, bevor es die Preview entfernt.

Prüfe zuerst, ob die Preview noch aktiv ist. Falls ja, verschiebe die App in einen sicheren Channel oder nutze die Updater-Reset-Aktion. Die Wahl hängt davon ab, wie deine Test-App konfiguriert ist. Eine Wegwerf-Test-App kann in ihren normalen Standard-Channel zurückkehren. Eine gemeinsam genutzte Test-App braucht eventuell einen eigenen Staging-Channel.

NutztresetPreviewwenn der Preview-Zustand direkt bereinigt werden muss. Kopple diesen Aufruf an denselben Pull Request und dieselbe App, die die Preview erstellt hat. Ein Cleanup-Script darf niemals ein Production-Device oder einen gemeinsam genutzten Release-Channel zurücksetzen, nur weil ein Channel-Name zufällig übereinstimmt.

Hier gilt eine hilfreiche Reihenfolge-Regel:

• Bestätige, dass der Pull Request geschlossen ist.
• Bestätige, dass kein Preview-Upload läuft.
• Wechsle von der aktiven Preview weg oder ruferesetPreview.
• Warte, bis die Zustandsänderung abgeschlossen ist.
• Rufe erst dann Delete Preview auf.

Betrachte eine erfolgreiche HTTP-Antwort auf den Reset-Request nicht als Beweis dafür, dass die App auf jedem Device bereits den Zustand geändert hat. Ein Device prüft Updates eventuell erst später. Dein serverseitiges Cleanup kann trotzdem fortfahren, sobald die Preview-Zuweisung laut der API Response gelöscht wurde, aber halte Device-Verhalten und Ressourcenlöschung getrennt.

Capgo unterstützt Channel-basiertes Rollout-Control, was diese Trennung leichter nachvollziehbar macht. Ein Channel ist ein benannter Pfad, der einer App sagt, welchem Update-Stream sie folgen soll. Dein Preview-Channel sollte niemals derselbe Channel sein, den Production-Devices nutzen.

Für Teams, die eine striktere Grenze brauchen, nutze den dokumentierten Capgo Channel-Workflow für Preview-Automatisierung. Er beschreibt das Muster für temporäre Channels und hilft, einen Cleanup-Job von gemeinsamen Default-Channels fernzuhalten.

Die Open-Source-Updater-Dokumentation hält auch das Löschlimit fest: Aktive Previews müssen zuerst umgeschaltet oder zurückgesetzt werden. Den Quellcode findest du im Capgo Capacitor Updater-Repository. Der Code hilft weiter, wenn die Formulierung im Dashboard für eine CI-Entscheidung zu knapp ist.

Pro-Tipp: Mache den Reset zu einem eigenen, geloggten Schritt. Falls 'Delete Preview' fehlschlägt, sollte im Log stehen, ob die Preview noch aktiv war oder ob die Löschanfrage ein anderes Problem hatte.

Sobald der aktive Status weg ist, kann der Preview-Datensatz gelöscht werden. Kombiniere Reset und Delete nicht in einer einzigen, undurchsichtigen Shell-Zeile. Zwei klare Befehle lassen sich leichter wiederholen und viel einfacher auditieren.

Schritt 4: Preview-Bundles per ID mit dem API Key löschen

Lösche jedes Preview-Bundle anhand seiner exakten ID, nachdem die aktive Preview zurückgesetzt wurde. Hier entfernt ein Capgo Cleanup-Key die Storage-Objekte, die der Pull Request hinterlassen hat.

Beginne mit der Bundle-Liste aus Schritt 2. Rufe für jede passende ID die 'Delete Bundle'-Aktion über die Capgo SDK oder die für deinen Account verfügbare öffentliche API Methode auf.

Prüfe die SDK-Methodensignatur oder bestätige die aktuelle Anfragestruktur mit Capgo-Support. Dokumentiere die Methode und das Antwortformat in deinem internen Runbook, sobald du sie verifiziert hast. Dieses Runbook sollte die API-Version, die benötigte Kennung und die Fehlercodes enthalten, die deine Retry-Logik verarbeiten kann.

Verwende einen Dry-Run-Modus in deinem Skript. Er sollte den Preview-Channel und die Bundle-IDs ausgeben, die entfernt würden, ohne Delete-Anfragen zu senden. Führe diesen Modus gegen mehrere geschlossene Pull Requests aus. Stelle sicher, dass er Produktions-Channel ausschließt und eine leere Liste nicht als Wildcard behandelt.

Eine sichere Löschschleife hat drei Kontrollpunkte:

1. Lehne eine fehlende oder fehlerhafte Bundle-ID ab.
2. Lehne ein Bundle ab, dessen Channel nicht mit dem Pull-Request-Preview übereinstimmt.
3. Lösche erst, nachdem der Ownership-Check bestanden hat.

Behandle dann jede Antwort nach Typ. Ein erfolgreiches Löschen kann als abgeschlossen erfasst werden. Eine Not-Found-Antwort kann als bereits bereinigt behandelt werden, wenn bekannt ist, dass die Ressource bei einem früheren Retry entfernt wurde. Berechtigungsfehler sollten den Job fehlschlagen lassen und den Owner benachrichtigen. Bei Rate-Limits sollte pausiert und mit einer begrenzten Verzögerung erneut versucht werden.

Versuche nicht jeden Fehler erneut. Eine ungültige ID wird nach drei Versuchen nicht gültig. Ein Autorisierungsfehler bedeutet in der Regel, dass der Key-Scope falsch ist. Versuche nur transiente Fehler erneut und setze eine maximale Laufzeit, damit ein festgefahrener Cleanup-Job deine CI-Queue nicht belegt.

Das Löschen von Bundles ist getrennt vom Löschen der Preview. Das Entfernen des Preview-Channels beweist nicht automatisch, dass jedes Bundle weg ist. Dein Job sollte für jede ID ein Ergebnis speichern und dann eine abschließende Listen-Anfrage stellen, falls API das unterstützt. Falls noch ein Bundle existiert, melde die ID und brich ab, anstatt stillschweigend Erfolg zu melden.

Halte die Lösch-Logs frei von Secrets. Es ist okay, die Pull-Request-Nummer, den Preview-Namen, die Bundle-ID, das Ergebnis der Anfrage und den Zeitstempel zu loggen. Logge niemals den API-Key, einen Authorization-Header oder ein vollständiges Request-Objekt, das einen enthalten könnte.

Dieser Ansatz gibt dir einen nützlichen Audit-Trail, ohne das Log zu einem weiteren Ort zu machen, an dem Credentials leaken könnten. Zudem lässt sich ein fehlgeschlagener Cleanup leicht fortsetzen, da der nächste Lauf Datensätze überspringen kann, die bereits als nicht vorhanden bestätigt wurden.

Schritt 5: Cleanup automatisieren, wenn ein Pull Request geschlossen wird

Starte den Cleanup-Job über das Pull-Request-Close-Event, aber baue Checks ein, die verhindern, dass ein verspäteter Build eine neue Preview löscht.

Dein Workflow sollte das Repository und die Pull-Request-Nummer aus dem Event-Payload erhalten. Rekonstruiere den Preview-Channel-Namen aus diesen Werten. Akzeptiere keinen Channel-Namen, der in einem Pull-Request-Kommentar oder einer nicht vertrauenswürdigen Branch-Variable angegeben wird.

Eine sinnvolle Job-Sequenz sieht so aus:

1. Lade den eingeschränkten Cleanup-Key aus verschlüsselten Secrets.
2. Bestätige, dass das Event ein geschlossener Pull Request ist.
3. Prüfe, ob die Preview zum erwarteten Repository und zur App gehört.
4. Warte, bis ein aktives Preview-Deployment abgeschlossen ist.
5. Wechsle von der Preview weg oder ruferesetPreview.
6. Bundle-IDs für diese Vorschau auflisten.
7. Jeden verifizierten Bundle löschen.
8. Den Preview-Eintrag löschen.
9. Ein kurzes Ergebnis in die Workflow-Zusammenfassung schreiben.

Die Reihenfolge ist entscheidend. Löschst du zuerst, kann die aktive Preview-Regel die Anfrage blockieren. Überspringst du den List-Call, weißt du eventuell nicht, welche Bundle-IDs noch existieren. Löschst du anhand eines geratenen Namens, riskierst du, die falsche Ressource zu treffen.

Nutze eine Concurrency-Regel, die an die Pull-Request-Nummer gekoppelt ist. Wenn ein Close-Event und ein Rebuild-Event fast gleichzeitig eintreffen, darf der alte Cleanup-Job nicht mit dem neuen Deployment konkurrieren. Brich veraltete Cleanup-Runs ab oder lass den Job warten, bis der Deployment-Lock frei ist.

Der Ein-Befehl-Workflow von Capgo für CLI kann die Anzahl manueller Shell-Aufrufe rund um Build- und Release-Prozesse reduzieren. Für Befehlsnamen und unterstützte Operationen schau in die Capgo CLI Befehlsdokumentation. Nutze CLI, wenn es dir einen verifizierten Befehl bietet. Nutze SDK oder die öffentliche API, wenn Cleanup-Aktionen eine direkte Anfrage erfordern.

Packe das Cleanup nicht in einen Workflow, der bei jedem Push läuft. Ein Push-Job könnte eine Preview löschen, die gerade noch getestet wird. Das Close-Event ist der richtige Trigger für das normale Cleanup. Füge einen manuellen Workflow-Dispatch zur Wiederherstellung hinzu, falls ein Job fehlschlägt.

Setzen Sie auch einen Retention-Fallback. Falls ein Close-Event verpasst wird, kann ein Scheduled Job Previews finden, die älter als das erlaubte Testfenster Ihres Teams sind. Dieser Job braucht strengere Schutzmaßnahmen als der normale Close-Hook. Er sollte nur Previews mit eindeutigem Owner und abgelaufenem Zeitstempel auswählen.

Halten Sie die Berechtigungen für GitHub Actions restriktiv und übergeben Sie nur die Werte, die der Cleanup-Schritt braucht. Die aktuelle Dokumentation zur GitHub Actions Integration von Capgo erklärt, wo der Token gespeichert wird und wie der Workflow mit Capgo verbunden wird.

Mittlerweile sollten Sie einen automatisierten Ablauf haben, der auf das Schließen reagiert, konkurrierende Jobs abwartet, den Active-State zurücksetzt, IDs auflistet und nur die passenden Bundles löscht. Das ist schnell genug für die tägliche Entwicklung, ohne dass der Cleanup zum Blindflug wird.

Schritt 6: Cleanup verifizieren und Rollouts vor versehentlichem Löschen schützen

Die Verifizierung schließt den Capgo Pull-Request-Preview-Cleanup-Loop. Eine bloße Löschbestätigung reicht für einen sicheren Release-Prozess nicht aus.

Prüfen Sie nach dem Cleanup-Job erneut den Preview-Channel. Bestätigen Sie, dass er nicht mehr als aktive Preview erscheint. Prüfen Sie dann die Bundle-Liste für dieselbe App und denselben Filter. Das erwartete Ergebnis ist, dass die gezielten Bundle-IDs verschwunden sind, während die Production-Bundles erhalten bleiben.

Speichern Sie diese Werte in der Job-Summary:

• Repository und Pull-Request-Nummer.
• Preview-Channel-Name.
• Commit-SHA für Ownership-Checks.
• Gefundene Bundle-IDs.
• Gelöschte Bundle-IDs.
• Alle IDs, die einen Fehler zurückgegeben haben.

Nutze klare Statusmeldungen. „Cleaned“ bedeutet, dass alle verifizierten Targets entfernt wurden. „Already clean“ bedeutet, dass die Ressource bereits vor diesem Durchlauf fehlte. „Needs review“ bedeutet, dass ein oder mehrere Checks fehlgeschlagen sind. Markiere eine Teil-Löschung niemals als Erfolg.

Füge in code eine Production-Guard hinzu. Lehne Channel-Namen wie deinen Default- oder Release-Channel ab. Lehne auch ein Bundle ab, wenn dessen Metadaten nicht zur Preview-App passen. Die Guard sollte nach dem Prinzip „fail closed“ arbeiten. Wenn das Skript das Target nicht eindeutig identifizieren kann, muss es stoppen.

Halte Rollback und Cleanup getrennt. Ein Rollback ändert, welches Bundle die Devices erhalten. Cleanup entfernt eine alte Preview-Ressource. Falls ein Test nach dem Schließen des Pull Requests einen Bug findet, brauchst du das Bundle eventuell zur Analyse. Setze ein kurzes Retention-Fenster statt sofortiger Löschung, falls dein Team oft nach dem Merge debuggt.

Achte auf diese drei gängigen Fehlermuster:

• Aktiver Preview-Fehler: Erst zurücksetzen oder wegwechseln, dann Delete Preview erneut versuchen.
• Bundle-ID fehlt: Führe die List-Action erneut aus, anstatt zu raten.
• Berechtigungsfehler: Prüfe den Key-Scope und erstelle bei Bedarf einen neuen Key.

Rotiere den Cleanup-Key nach dem Zeitplan, den deine Security-Policy vorgibt, und sofort, falls er in einem Log oder Commit auftaucht. Teste einen neuen Key, bevor der alte widerrufen wird, es sei denn, die Exponierung erfordert einen sofortigen Widerruf.

Die Dokumentationslücke rund um Cleanup sollte in Ihrem Security Review vermerkt werden. Nutzen Sie die SDK und die verifizierten Capgo Hinweise als Grundlage für Ihre Implementierung und halten Sie Ihren eigenen Request-Contract unter Versionskontrolle.

Das Wichtigste in Kürze: Überprüfen Sie die Preview- und Bundle-Liste nach dem Löschen, blockieren Sie Production-Targets in code und melden Sie ein unvollständiges Cleanup als Fehler.

Ein Befehl ist nur nützlich, wenn die Guardrails klar sind. Tracken Sie die Preview. Verwenden Sie einen vorhersehbaren Channel-Namen. Rollen Sie Release-Änderungen separat zurück. Lassen Sie den Cleanup-Job dann seine kleine Aufgabe erledigen, ohne Live-Traffic anzufassen.

FAQ

Kann ich eine aktive Capgo Pull-Request-Preview löschen?

Nein. Eine aktive Preview muss zuerst umgestellt werden, oder Sie müssenresetPreview aufrufen. Sobald der aktive Status aufgehoben ist, führen Sie Delete Preview aus. Diese Regel ist das wichtigste Detail beim Einrichten eines Capgo Pull-Request-Preview-Cleanup-API-Keys in der CI.

Brauche ich Bundle-IDs, um eine Capgo Preview zu bereinigen?

Ja. Die Delete-Bundle-Aktion von Capgo erfordert die Bundle-IDs; listen Sie die verfügbaren Bundles also vor dem Löschen auf. Ordnen Sie jede ID dem Preview-Channel zu und committen Sie, bevor Sie den Delete-Request senden. Leiten Sie eine ID niemals aus einem Branch-Namen ab und gehen Sie nicht davon aus, dass das Löschen der Preview auch alle Bundles entfernt.

Was für einen API Key sollte die CI für das Preview-Cleanup verwenden?

Verwende einen eingeschränkten App-Preview-Key für das Preview-Cleanup, gespeichert im verschlüsselten Secret Store deines CI-Anbieters. Beschränke den Key auf die App oder den benötigten Scope. Halte ihn getrennt vom Key, mit dem Produktions-Updates veröffentlicht werden. So lässt sich der Capgo-Cleanup-Job leichter prüfen und sicherer rotieren.

Kann ich die Bereinigung beim Schließen eines Pull Requests automatisieren?

Ja. Löse das Cleanup über das Event für geschlossene Pull Requests aus und warte auf aktive Deployment-Jobs, bevor du die Preview zurücksetzt. Liste die Bundle-IDs auf, lösche verifizierte Treffer und bestätige das Ergebnis. Füge Concurrency-Kontrollen hinzu, damit ein verspäteter Build dem Cleanup-Job nicht in die Quere kommt.

Warum schlägt meine Capgo-Cleanup-Anfrage fehl?

Die üblichen Ursachen sind eine aktive Preview, eine fehlende Bundle-ID oder ein Key ohne den benötigten Scope. Setze zuerst die Preview zurück, wiederhole den List-Aufruf und prüfe die Key-Berechtigungen. Da die Details der Anfrage je nach API- oder SDK-Version variieren können, bestätige die aktuelle Methode und die Parameter, bevor du das Skript änderst.

Fazit

Verwende Capgo mit einem dedizierten Preview-Key und einer strikten Cleanup-Reihenfolge: Setze die aktive Preview zurück, liste ihre Bundle-IDs auf, lösche verifizierte Bundles und entferne dann die Preview. Beginne mit einem Dry Run gegen einen geschlossenen Pull Request, bestätige die Request-Form im aktuellen SDK und füge den Guard für den Produktionskanal hinzu, bevor du das automatische Cleanup aktivierst.