Capgo Pulizia delle Pull Request Preview API Key

Eliminare una pull request preview sembra un'operazione da un solo comando. Con Capgo, c'è un intoppo: devi uscire da una preview attiva prima di eliminarla, poi rimuovere i relativi bundle tramite ID. Creeremo un flusso di pulizia sicuro con una API key limitata, ricerca delle preview, gestione del reset, eliminazione dei bundle e automazione CI.

Indice dei contenuti

• Passo 1: Crea una Capgo API key limitata per la pulizia delle preview
• Passo 2: Identifica la pull request preview e i relativi bundle ID
• Passo 3: Passa via dalla anteprima attiva prima della pulizia
• Passo 4: Elimina i bundle di anteprima per ID con la chiave API
• Passo 5: Automatizza la pulizia quando una pull request viene chiusa
• Passaggio 6: Verifica il cleanup e proteggi i rollout da eliminazioni accidentali
• FAQ
• Conclusione

Passo 1: Crea una Capgo API key limitata per la pulizia delle preview

Il primo passo in un flusso di pulizia delle pull request preview di Capgo è creare una chiave che possa eseguire solo le operazioni necessarie al tuo job CI.

Non inserire una chiave organizzativa ampia in un workflow di pull request. Una pull request può provenire da una branch che non ha ancora guadagnato fiducia. Il workflow potrebbe inoltre stampare un comando o un valore di ambiente durante un'esecuzione fallita. Una chiave ristretta limita i danni se ciò accade.

In Capgo, inizia con una chiave App Preview per il lavoro di anteprima. La chiave deve essere legata all'app o allo scope di anteprima gestito dal tuo job. Se il tuo team usa il controllo degli accessi basato sui ruoli, limita la chiave alle app selezionate invece di concedere accesso a tutta l'organizzazione. Capgo documenta queste scelte per le chiavi di anteprima nel suo API impostazioni chiave per i workflow delle web app.

Conserva il segreto nello store dei segreti cifrati del tuo provider CI. Dagli un nome che indichi la sua funzione, ad esempioCAPGO_PREVIEW_CLEANUP_KEY. Non inserirlo in un file di workflow, script shell, commento di pull request o log generato.

Passa la chiave al processo di pulizia tramite una variabile d'ambiente. Il tuo script deve fallire se la variabile è assente. Un fallback silenzioso è pericoloso perché può trasformare un job di pulizia in una richiesta senza autenticazione, o indurre uno sviluppatore a incollare una chiave nella riga di comando.

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

Tieni questa chiave separata da quella usata per pubblicare i bundle di produzione. Il job di publish potrebbe dover caricare un release. Il job di cleanup ha bisogno solo di rimuovere le risorse di preview. Chiavi separate facilitano la review e riducono il rischio che un'azione di eliminazione raggiunga un canale di produzione.

Usa lo stesso secret in un ambiente protetto quando possibile. Richiedi l'approvazione prima che un job possa toccare canali condivisi. Per le preview di pull request ordinarie, il job dovrebbe lavorare su un canale temporaneo e nient'altro.

In sintesi: Usa una chiave App Preview dedicata, limita il suo ambito app e conservala nei secret CI cifrati.

Prima di procedere, testa la chiave con un'azione di lettura innocua. Conferma che il job può vedere l'app prevista, ma non può accedere a un'app non correlata o a un workflow di produzione. I dettagli esatti della richiesta per il cleanup non sono completamente pubblicati, quindi mantieni il primo test piccolo e ispeziona la guida di supporto di SDK o Capgo prima di aggiungere chiamate di eliminazione.

Passo 2: Identifica la pull request preview e i relativi bundle ID

La chiave API per la pulizia delle anteprime delle pull request Capgo è utile solo se il tuo job sa quali ID di anteprima e bundle possiede.

Usa una regola di naming stabile per i canali di preview. Un pattern comune è il nome del repository più il numero della pull request. Il punto chiave è la coerenza. Il tuo job di cleanup deve ricostruire lo stesso identificatore dopo la chiusura della pull request.

Salva il nome del canale di preview quando viene creato. Puoi inserirlo nell'output del workflow, in un check della pull request o in un piccolo campo di metadati del job. Non fare affidamento su un nome visualizzabile che qualcuno potrebbe modificare nel dashboard.

Successivamente, elenca i bundle associati a quella preview. L'azione Delete Bundle di Capgo richiede gli ID dei bundle. La documentazione di origine indica una chiamata list per recuperare tutti gli ID dei bundle disponibili prima della cancellazione. Considera quell'elenco come fonte di verità. Non indovinare mai un ID da un nome file, un hash di commit o un nome di branch.

Filtra i record restituiti per il canale di preview o per un altro valore controllato dal tuo workflow. Quindi conserva l'ID esatto del bundle per ogni corrispondenza. Se l'elenco è vuoto, segna la pulizia come completata. Un risultato vuoto non è un errore a meno che il tuo workflow non si aspettasse l'esistenza di una preview.

Registra anche il SHA del commit che ha generato ciascuna preview. Questo ti fornisce un secondo controllo prima della cancellazione. Se il nome del canale corrisponde ma il commit no, fermati e richiedi una revisione. Questa breve pausa può prevenire una race condition in cui una nuova preview viene creata mentre un vecchio job di pulizia è in esecuzione.

Non cancellare mentre un job di publish è ancora in esecuzione. Aggiungi una dipendenza tra i workflow di build della preview e di pulizia, oppure usa un lock basato sul numero della pull request. Il job di pulizia deve avviarsi solo dopo l'evento di chiusura e dopo la fine di qualsiasi upload di preview pendente.

L'API pubblico di Capgo copre risorse come canali e bundle tramite richieste HTTP autenticate, ma le azioni di pulizia richiedono ancora una verifica accurata nel tuo progetto. Il panoramica dell'API pubblico di Capgo è il posto giusto per confermare il modello di risorse attuale prima di scrivere un wrapper.

A questo punto dovresti avere un identificatore di anteprima, un elenco di ID bundle esatti e il SHA del commit associato a ciascun record. Se uno di questi valori è mancante, fermati qui. La pulizia senza controlli di proprietà è pura congettura.

Passo 3: Passa via dall'anteprima attiva prima della pulizia

Un'anteprima attiva non può essere eliminata finché l'app non passa via da essa o non chiamiresetPreview. Questo è il dettaglio chiave nel flusso di pulizia delle anteprime di pull request di Capgo.

Pensa all'anteprima attiva come alla versione attualmente selezionata dall'app. Eliminare prima il record lato server lascerebbe l'app puntata a qualcosa che non esiste più. Capgo blocca quel cambio di stato, quindi il tuo job di pulizia deve reimpostare lo stato di anteprima dell'app prima di rimuovere l'anteprima.

Prima controlla se la preview è ancora attiva. In caso affermativo, sposta l'app su un canale sicuro o usa l'azione di reset dell'updater. La scelta dipende da come è configurata la tua app di test. Un'app di test usa e getta può tornare al suo canale di default, mentre un'app di test condivisa potrebbe richiedere un canale di staging dedicato.

UsaresetPreviewquando lo stato della preview deve essere azzerato direttamente. Mantieni questa chiamata legata alla stessa pull request e all'app che ha creato la preview. Uno script di cleanup non deve mai resettare un dispositivo in produzione o un canale di release condiviso solo perché il nome del canale coincide.

C'è una regola utile per l'ordine:

• Verifica che la pull request sia chiusa.
• Conferma che non è in corso alcun upload di preview.
• Esci dalla preview attiva o chiamaresetPreview.
• Attendi che il cambio di stato sia completato.
• Solo allora chiama Delete Preview.

Non considerare una risposta HTTP di successo alla richiesta di reset come prova che l'app abbia già cambiato stato su ogni dispositivo. Un dispositivo potrebbe controllare gli update più tardi. Il cleanup lato server può comunque procedere una volta rimossa l'assegnazione della preview in base alla risposta API, ma tieni separato il comportamento del dispositivo dalla cancellazione delle risorse.

Capgo supporta il controllo del rollout basato sui canali, il che rende più semplice ragionare su questa separazione. Un canale è un percorso denominato che indica all'app quale stream di update seguire. Il tuo canale di preview non deve mai essere lo stesso usato dai dispositivi in produzione.

Per i team che necessitano di confini più rigidi, utilizza la documentata Workflow del canale Capgo per l'automazione delle anteprime. Descrive il pattern dei canali temporanei e aiuta a mantenere un job di pulizia separato dai canali predefiniti condivisi.

La documentazione dell'updater open source registra anche il limite di eliminazione: le preview attive richiedono prima uno switch o un reset. Puoi consultare il sorgente nel repository updater di Capgo Capacitor. Quel sorgente è utile quando la descrizione nel dashboard è troppo sintetica per una decisione CI.

Consiglio pro: Rendi il reset un passo separato e tracciato nei log. Se Delete Preview fallisce, il log dovrebbe mostrare se la preview era ancora attiva o se la richiesta di eliminazione aveva un altro problema.

Una volta rimosso lo stato attivo, il record della preview è pronto per l'eliminazione. Non combinare reset ed eliminazione in un'unica riga shell opaca. Due comandi chiari sono più facili da ritentare e molto più facili da auditare.

Passo 4: Elimina i Bundle di Preview per ID con la chiave API

Elimina ogni bundle di preview per il suo ID esatto, dopo che la preview attiva è stata resettata. È qui che una chiave di pulizia Capgo rimuove gli oggetti di storage lasciati dalla pull request.

Inizia con l'elenco dei bundle dal Passo 2. Per ogni ID corrispondente, chiama l'azione Delete Bundle tramite Capgo SDK o il metodo pubblico API attuale disponibile per il tuo account.

Controlla la firma del metodo SDK o conferma la struttura attuale della richiesta con il supporto di Capgo. Dopo averli verificati, registra il metodo e il formato della risposta nel runbook interno del team. Il runbook deve includere la versione API, l'identificatore richiesto e i codici di errore che la tua logica di retry può gestire.

Usa una modalità dry-run nel tuo script. Dovrebbe stampare il canale preview e i bundle ID che rimuoverebbe, senza inviare richieste DELETE. Esegui quella modalità su diverse pull request chiuse. Verifica che escluda i canali di produzione e che non tratti una lista vuota come un wildcard.

Un loop di cancellazione sicuro ha tre controlli:

1. Rifiuta un bundle ID mancante o malformato.
2. Rifiuta un bundle il cui canale non corrisponde alla preview della pull request.
3. Elimina solo dopo il superamento del controllo di ownership.

Gestisci poi ogni risposta in base al tipo. Una cancellazione riuscita può essere registrata come completata. Una risposta 'not-found' può essere considerata già pulita se è noto che la risorsa è stata rimossa da un retry precedente. Gli errori di autorizzazione devono far fallire il job e avvisare il proprietario. I rate limit devono mettere in pausa e riprovare con un ritardo massimo.

Non riprovare ogni errore. Un ID errato non diventerà valido dopo tre tentativi. Un errore di autorizzazione di solito indica che lo scope della chiave è sbagliato. Riprova solo in caso di errori transitori e imposta un tempo massimo di esecuzione per evitare che un job di cleanup bloccato consumi la tua coda CI.

La cancellazione dei bundle è separata dalla cancellazione delle preview. Rimuovere il canale di preview non garantisce automaticamente che tutti i bundle siano stati eliminati. Il tuo job dovrebbe conservare un risultato per ogni ID, quindi effettuare una richiesta finale di elenco se API lo supporta. Se un bundle rimane, riporta l'ID e interrompi invece di dichiarare silenziosamente il successo.

Mantieni i log di eliminazione privi di segreti. Va bene registrare il numero della pull request, il nome della preview, il bundle ID, il risultato della richiesta e il timestamp. Non registrare mai la chiave API, un header di autorizzazione o un intero oggetto richiesta che potrebbe contenerne uno.

Questo approccio ti dà un audit trail utile senza trasformare i log in un altro punto da cui possono trapelare le credenziali. Rende anche facile riprendere una pulizia fallita, perché l'esecuzione successiva può saltare i record già confermati come assenti.

Passo 5: Automatizza la pulizia alla chiusura di una pull request

Esegui il job di pulizia dall'evento di chiusura della pull request, ma aggiungi controlli che impediscano a una build tardiva di eliminare una preview nuova.

Il tuo workflow dovrebbe ricevere il repository e il numero della pull request dal payload dell'evento. Ricostruisci il nome del canale di preview da questi valori. Non accettare un nome di canale fornito da un commento alla pull request o da una variabile di branch non fidata.

Una sequenza di job utile è questa:

1. Carica la chiave di pulizia ristretta dai segreti crittografati.
2. Conferma che l'evento sia una pull request chiusa.
3. Verifica che la preview appartenga al repository e all'app attesi.
4. Attendi che eventuali deployment di preview in corso finiscano.
5. Esci dalla preview o chiamaresetPreview.
6. Elenca i bundle ID di quella preview.
7. Elimina ogni bundle verificato.
8. Elimina il record della preview.
9. Scrivi un breve risultato nel summary del workflow.

L'ordine è fondamentale. Se elimini prima, la regola di preview attiva può bloccare la richiesta. Se salti la chiamata di elenco, potresti non sapere quali bundle ID esistono ancora. Se elimini usando un nome ipotizzato, rischi di toccare la risorsa sbagliata.

Usa una regola di concorrenza basata sul numero della pull request. Quando un evento di chiusura e uno di rebuild arrivano quasi contemporaneamente, il vecchio job di pulizia non deve andare in race condition con il nuovo deployment. Annulla una pulizia obsoleta o fai attendere il job finché il lock del deployment non si libera.

Il workflow CLI con un solo comando di Capgo può ridurre il numero di chiamate shell custom durante build e release. Per i nomi dei comandi e le operazioni supportate, consulta la documentazione del comando CLI di Capgo. Usa CLI quando ti dà un comando verificato. Usa SDK o la API pubblica quando le azioni di pulizia richiedono una chiamata diretta.

Non inserire la pulizia in un workflow che gira a ogni push. Un job di push può rimuovere una preview ancora in fase di test. L'evento di chiusura è il trigger corretto per la pulizia normale. Aggiungi un workflow dispatch manuale per il recupero quando un job fallisce.

Imposta anche un fallback di retention. Se un evento di chiusura va perso, un job pianificato può trovare preview più vecchie della finestra di test consentita dal tuo team. Quel job richiede salvaguardie più rigorose rispetto al normale hook di chiusura. Dovrebbe selezionare solo preview con un owner identificato e un timestamp scaduto.

Per le GitHub Actions, mantieni i permessi ristretti e passa solo i valori necessari allo step di cleanup. La documentazione attuale dell'integrazione GitHub Actions di Capgo spiega dove viene memorizzato il token e come il workflow si connette a Capgo.

A questo punto dovresti avere un percorso automatizzato che reagisce alla chiusura, attende i job concorrenti, resetta lo stato attivo, elenca gli ID e cancella solo i bundle corrispondenti. È abbastanza veloce per lo sviluppo quotidiano senza che il cleanup diventi una pulizia cieca.

Passaggio 6: Verifica il cleanup e proteggi i rollout da eliminazioni accidentali

La verifica chiude il loop di cleanup delle preview delle pull request di Capgo. Una semplice risposta di eliminazione non basta per un processo di rilascio sicuro.

Dopo l'esecuzione del job di cleanup, controlla di nuovo il canale preview. Conferma che non compaia più come preview attiva. Poi controlla la lista dei bundle per la stessa app e con lo stesso filtro. Il risultato atteso è che i bundle ID target siano spariti, mentre i bundle di produzione rimangono.

Salva questi valori nel riepilogo del job:

• Repository e numero della pull request.
• Nome del canale preview.
• Commit SHA usato per i controlli di ownership.
• Bundle ID trovati.
• Bundle ID eliminati.
• Gli eventuali ID che hanno restituito un errore.

Usa uno stato chiaro. “Cleaned” significa che ogni target verificato è stato rimosso. “Already clean” indica che la risorsa era già assente prima di questa esecuzione. “Needs review” significa che uno o più controlli sono falliti. Non etichettare una rimozione parziale come successo.

Aggiungi un guard di produzione in code. Rifiuta nomi di canale come il tuo canale predefinito o di release. Rifiuta anche un bundle se i suoi metadati non corrispondono all'app di preview. Il guard deve fallire in modo sicuro (fail closed). Se lo script non può identificare il target con certezza, deve fermarsi.

Tieni separati rollback e cleanup. Un rollback cambia quale bundle ricevono i dispositivi. Il cleanup rimuove una risorsa di preview vecchia. Se un test trova un bug dopo la chiusura della pull request, potresti aver bisogno del bundle per l'indagine. Imposta una finestra di retention breve invece di eliminare subito all'arrivo dell'evento, se il tuo team spesso fa debug dopo il merge.

Attenzione a tre pattern di fallimento comuni:

• Errore di preview attiva: reset o passa a un altro stato prima di ritentare Delete Preview.
• Bundle ID mancante: esegui di nuovo l'azione list invece di indovinare.
• Errore di permessi: controlla lo scope della chiave, poi emetti una nuova chiave se necessario.

Ruota la chiave di cleanup secondo la pianificazione definita dalla tua policy di sicurezza, e ruotala immediatamente se appare in un log o in un commit. Una nuova chiave deve essere testata prima che quella vecchia venga revocata, a meno che l'esposizione non richieda una revoca immediata.

La lacuna di documentazione sul cleanup merita una nota nella tua revisione di sicurezza. Considera le linee guida su SDK e quelle verificate su Capgo come fonte per l'implementazione, e tieni il contratto delle tue richieste sotto controllo di versione.

In sintesi: Verifica l'elenco di preview e bundle dopo l'eliminazione, blocca i target di produzione in code e segnala il cleanup parziale come un errore.

Un comando è utile solo quando i guardrail sono chiari. Tieni traccia della preview. Adotta un nome di canale prevedibile. Fai rollback delle modifiche di release separatamente. Poi lascia che il job di cleanup faccia il suo piccolo lavoro senza toccare il traffico live.

FAQ

Posso eliminare una preview attiva di una pull request Capgo?

No. Devi prima disattivare la preview attiva, oppure chiamareresetPreview. Una volta rimosso lo stato attivo, esegui Delete Preview. Questa regola è il dettaglio principale da ricordare quando configuri in CI una chiave API per il cleanup delle preview delle pull request Capgo.

Mi servono gli ID dei bundle per fare cleanup di una preview Capgo?

Sì. L'azione Delete Bundle di Capgo richiede gli ID dei bundle, quindi elenca i bundle disponibili prima di eliminarli. Abbina ogni ID al canale di preview e al commit prima di inviare una richiesta di eliminazione. Non costruire mai un ID dal nome di un branch e non dare per scontato che eliminare la preview rimuova anche tutti i bundle.

Quale tipo di chiave API dovrebbe usare la CI per il cleanup delle preview?

Usa una chiave App Preview con restrizioni per la pulizia delle preview, salvata nel vault dei segreti cifrati del tuo provider CI. Limita la chiave all'app o allo scope necessario. Tienila separata dalla chiave usata per pubblicare gli aggiornamenti di produzione. Questo rende il job di pulizia Capgo più facile da revisionare e più sicuro da ruotare.

Posso automatizzare la pulizia quando una pull request viene chiusa?

Sì. Attiva la pulizia dall'evento di chiusura della pull request, poi attendi il completamento dei job di deployment attivi prima di resettare la preview. Elenca gli ID dei bundle, elimina le corrispondenze verificate e conferma il risultato. Aggiungi controlli di concorrenza per evitare che un build tardivo interferisca con il job di pulizia.

Perché la mia richiesta di pulizia Capgo sta fallendo?

Le cause più comuni sono una preview attiva, un ID bundle mancante o una chiave senza lo scope necessario. Resetti prima la preview, ripeti la chiamata di elenco e ispeziona i permessi della chiave. Poiché i dettagli della richiesta possono variare in base alla versione di API o SDK, verifica il metodo e i parametri correnti prima di modificare lo script.

Conclusione

Usa Capgo con una chiave preview dedicata e un ordine di pulizia rigoroso: resetta la preview attiva, elenca i suoi ID bundle, elimina i bundle verificati, poi rimuovi la preview. Inizia con una dry run su una pull request chiusa, conferma la struttura della richiesta nella versione corrente di SDK e aggiungi la guardia per il canale di produzione prima di attivare la pulizia automatica.