Capgo Pull Request Preview Cleanup API Key

Das Löschen einer Pull Request Preview wirkt wie ein Ein-Befehl-Job. Aber Capgoes gibt einen Haken: Du musst eine aktive Preview verlassen, bevor du sie löschst, und dann die 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: Erstelle einen eingeschränkten Capgo API Key für den Preview Cleanup
• Schritt 2: Identifiziere die Pull Request Preview und deren Bundle IDs
• Schritt 3: Die aktive Preview vor dem Cleanup verlassen
• Schritt 4: Preview Bundles per ID mit dem API Key löschen
• Schritt 5: Cleanup bei geschlossenem Pull Request automatisieren
• Schritt 6: Cleanup prüfen und Rollouts vor versehentlichem Löschen schützen
• FAQ
• Fazit

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

Der erste Schritt in einem Capgo Pull Request Preview Cleanup Flow ist die Erstellung eines Keys, der nur die Aufgaben übernimmt, die dein CI-Job benötigt.

Verwende keinen weit 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 eingeschränkter Key minimiert 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 seine Funktion beschreibt, 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.

Nutze eine stabile Benennungsregel für Preview-Channels. Ein gängiges Muster ist der Repository-Name plus die Pull-Request-Nummer. Entscheidend ist die Konsistenz. Dein Cleanup-Job muss nach dem Schließen des Pull Requests denselben Identifier wiederfinden.

Speichere den Namen des Preview-Channels direkt bei der Erstellung. Du kannst ihn im Workflow-Output, einem Pull-Request-Check oder in den Job-Metadaten hinterlegen. Verlasse dich nicht auf einen Anzeigenamen, den jemand manuell im Dashboard ändern könnte.

Liste als Nächstes die Bundles auf, die mit dieser Preview verknüpft sind. Die Delete Bundle Action von Capgo benötigt Bundle IDs. Die Dokumentation empfiehlt einen List-Call, um alle verfügbaren Bundle IDs vor dem Löschen abzurufen. Nutze diese Liste als einzige Quelle der Wahrheit. Rate niemals IDs anhand von Dateinamen, Commit-Hashes oder Branch-Namen.

Filtere die Ergebnisse nach dem Preview-Channel oder einem anderen Wert, den dein Workflow steuert. Behalte dann die exakte Bundle ID für jeden Treffer. Wenn die Liste leer ist, markiere den Cleanup als abgeschlossen. Ein leeres Ergebnis ist kein Fehler, es sei denn, dein Workflow hat zwingend eine Preview erwartet.

Protokolliere zusätzlich den Commit SHA, der die jeweilige Preview erzeugt hat. Das dient als zweite Absicherung vor dem Löschen. Wenn der Channel-Name passt, aber der Commit nicht, stoppe den Prozess und fordere ein Review an. Diese kurze Pause verhindert Race Conditions, falls gerade eine neue Preview gebaut wird, während ein alter Cleanup-Job läuft.

Lösche nichts, solange noch ein Publish-Job läuft. Füge eine Abhängigkeit zwischen dem Preview-Build und dem Cleanup-Workflow hinzu oder nutze einen Lock, der an die Pull-Request-Nummer gebunden ist. Der Cleanup-Job sollte erst nach dem Close-Event und nach Abschluss aller ausstehenden Preview-Uploads starten.

Capgo’s öffentliche API deckt Ressourcen wie Channels und Bundles über authentifizierte HTTP-Requests ab, aber die Cleanup-Aktionen müssen in deinem Projekt dennoch sorgfältig geprüft werden. Die Capgo öffentliche API Übersicht ist der richtige Ort, um das aktuelle Ressourcenmodell zu bestätigen, bevor du einen Wrapper schreibst.

Mittlerweile solltest du eine Preview-ID, eine Liste der exakten Bundle-IDs und die Commit-SHA für jeden Datensatz haben. Falls einer dieser Werte fehlt, stoppe hier. Ein Cleanup ohne Ownership-Checks ist reine Raterei.

Schritt 3: Die aktive Preview vor dem Cleanup verlassen

Eine aktive Preview kann nicht gelöscht werden, bis die App zu einer anderen Version wechselt oder duresetPreviewDies ist das entscheidende Detail im Capgo Pull Request Preview Cleanup-Workflow.

Betrachte die aktive Preview als die Version, die aktuell von der App ausgewählt ist. Würdest du zuerst den Datensatz serverseitig löschen, würde die App auf etwas zeigen, das nicht mehr existiert. Capgo blockiert diesen Zustandswechsel, daher muss dein Cleanup-Job den Preview-Status der App zurücksetzen, bevor er 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 von der Konfiguration deiner Test-App ab. Eine kurzlebige Test-App kann zu ihrem normalen Default-Channel zurückkehren. Eine gemeinsam genutzte Test-App benötigt eventuell einen dedizierten Staging-Channel.

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

Hierfür gibt es eine hilfreiche Reihenfolge:

• Bestätige, dass der Pull Request geschlossen ist.
• Bestätige, dass kein Preview-Upload läuft.
• Wechsle aus der aktiven Preview oder dem Aufruf wegresetPreview.
• Warte, bis die Statusänderung abgeschlossen ist.
• Erst dann: Delete Preview aufrufen.

Betrachte eine erfolgreiche HTTP-Response des Reset-Requests nicht als Beweis, dass die App auf jedem Device bereits den Status gewechselt hat. Ein Device prüft Updates eventuell erst später. Dein serverseitiges Cleanup kann fortgesetzt werden, sobald die Preview-Zuweisung gemäß der API Response gelöscht wurde; trenne jedoch das Device-Verhalten strikt von der Ressourcenlöschung.

Capgo unterstützt Channel-basiertes Rollout-Control, was diese Trennung logisch vereinfacht. 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 Trennung benötigen, nutzen Sie 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 Request-Struktur über den Capgo Support. Dokumentiere die Methode und das Antwortformat in eurem internen Runbook, sobald du sie verifiziert hast. Das Runbook sollte die API Version, die erforderliche ID und die Fehlercodes enthalten, die deine Retry-Logik verarbeiten kann.

Nutze einen Dry-Run-Modus in deinem Skript. Dieser sollte den Preview-Channel und die Bundle-IDs ausgeben, die gelöscht würden, ohne echte Delete-Requests zu senden. Teste diesen Modus mit mehreren geschlossenen Pull Requests. Stelle sicher, dass Production-Channels ausgeschlossen werden und eine leere Liste nicht als Wildcard interpretiert wird.

Eine sichere Deletion-Schleife hat drei Gates:

1. Lehne fehlende oder fehlerhafte Bundle-IDs ab.
2. Lehne Bundles ab, deren Channel nicht mit dem Pull Request Preview übereinstimmt.
3. Lösche erst, nachdem der Ownership-Check erfolgreich war.

Verarbeite anschließend jede Response nach Typ. Ein erfolgreiches Delete kann als abgeschlossen markiert werden. Eine 'Not-found'-Response kann als bereits bereinigt gelten, wenn die Ressource durch einen vorherigen Retry entfernt wurde. Permission-Errors sollten den Job abbrechen und den Owner benachrichtigen. Rate Limits sollten den Prozess pausieren und mit einem begrenzten Delay erneut versuchen.

Versuche nicht, jeden Fehler zu wiederholen. Eine ungültige ID wird auch nach drei Versuchen nicht valide. Ein Authorization-Error bedeutet meist, dass der Key-Scope falsch ist. Retry nur transiente Fehler und setze ein maximales Laufzeitlimit, damit ein hängender Cleanup-Job nicht deine CI-Queue blockiert.

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. Liste die Bundle-IDs für diese Preview auf.
7. Lösche jedes verifizierte Bundle.
8. Lösche den Preview-Eintrag.
9. Schreibe ein kurzes Ergebnis in die Workflow-Summary.

Die Reihenfolge ist entscheidend. Wenn du zuerst löschst, kann die aktive Preview-Rule die Anfrage blockieren. Wenn du den List-Call überspringst, weißt du eventuell nicht, welche Bundle-IDs noch existieren. Wenn du nach einem geschätzten Namen löschst, riskierst du, die falsche Ressource zu treffen.

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

Der Ein-Befehl-Workflow von Capgo für CLI kann die Anzahl benutzerdefinierter 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 liefert. 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 für die Wiederherstellung hinzu, falls ein Job fehlschlägt.

Setzen Sie auch einen Retention-Fallback. Falls ein Close-Event verpasst wird, kann ein Scheduled Job nach Previews suchen, die älter als das erlaubte Testfenster Ihres Teams sind. Dieser Job benötigt strengere Sicherheitsvorkehrungen als der normale Close-Hook. Er sollte nur Previews mit einem eindeutigen Owner und einem abgelaufenen Zeitstempel auswählen.

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

Bis jetzt sollten Sie einen automatisierten Pfad 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 blinden Besen wird.

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

Die Verifizierung schließt den Capgo Pull Request Preview Cleanup Loop ab. Eine bloße Delete-Response 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. Überprü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 Status. „Cleaned“ bedeutet, dass alle verifizierten Targets gelöscht 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.

Implementiere eine Production-Guard in code. 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. Wenn ein Test nach dem Pull Request einen Bug findet, benötigst 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 typischen Fehlermuster:

• Aktiver Preview-Fehler: Reset oder Switch durchführen, bevor Delete Preview erneut versucht wird.
• Fehlende Bundle-ID: Führe die List-Action erneut aus, statt zu raten.
• Permission-Error: Prüfe den Key-Scope und erstelle bei Bedarf einen neuen Key.

Rotiere den Cleanup-Key nach einem Zeitplan deiner Security-Policy, und sofort, falls er in einem Log oder Commit auftaucht. Teste einen neuen Key, bevor der alte widerrufen wird, es sei denn, die Exposure erfordert eine sofortige Revocation.

Die Dokumentationslücke beim Cleanup sollte in Ihrem Security-Review berücksichtigt werden. Nutzen Sie die SDK und verifizierten Capgo Richtlinien als Basis für Ihre Implementierung und halten Sie Ihren eigenen Request-Contract unter Versionskontrolle.

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

Ein einzelner Befehl ist nur dann nützlich, wenn die Guardrails klar definiert sind. Tracken Sie die Preview. Nutzen Sie einen vorhersehbaren Channel-Namen. Rollen Sie Release-Änderungen separat zurück. Lassen Sie den Cleanup-Job dann seine Arbeit erledigen, ohne den Live-Traffic zu beeinflussen.

FAQ

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

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

Benötige ich Bundle IDs, um eine Capgo Preview zu bereinigen?

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

Welche Art von API Key sollte die CI für das Preview-Cleanup verwenden?

Nutze einen eingeschränkten App Preview Key für das Cleanup, der in deinem verschlüsselten Secret Store des CI-Providers liegt. Limitiere den Key auf die benötigte App oder den Scope. Halte ihn getrennt vom Key für Production Updates. Das macht den Capgo Cleanup-Job einfacher zu prüfen und sicherer beim Rotieren.

Can I automate cleanup when a pull request closes?

Ja. Trigger das Cleanup über das 'closed pull request'-Event und warte auf aktive Deployment-Jobs, bevor du die Preview zurücksetzt. Liste die Bundle IDs auf, lösche die verifizierten Matches und bestätige das Ergebnis. Nutze Concurrency-Controls, damit ein verspäteter Build nicht mit dem Cleanup-Job kollidiert.

Warum schlägt mein Capgo Cleanup-Request fehl?

Typische Ursachen sind eine aktive Preview, eine fehlende Bundle ID oder ein Key ohne den nötigen Scope. Setze die Preview zuerst zurück, wiederhole den List-Call und prüfe die Key-Berechtigungen. Da die Request-Details je nach API oder SDK Version variieren können, prüfe die aktuelle Methode und die Parameter, bevor du das Skript änderst.

Fazit

Nutze Capgo mit einem dedizierten Preview Key und einer strikten Cleanup-Reihenfolge: Setze die aktive Preview zurück, liste die Bundle IDs auf, lösche die verifizierten Bundles und entferne dann die Preview. Starte mit einem Dry Run für einen geschlossenen Pull Request, bestätige das Request-Format in der aktuellen SDK und füge eine Production-Channel-Guard hinzu, bevor du das automatische Cleanup aktivierst.