Integrazione CI/CD
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Integrare Capgo nella tua pipeline CI/CD ti consente di automatizzare completamente la build e il deployment degli aggiornamenti della tua app. Sfruttando Capgo CLI e semantic-release, puoi garantire deployment coerenti e affidabili e consentire iterazioni rapide.
Vantaggi dell'integrazione CI/CD
Sezione intitolata “Vantaggi dell'integrazione CI/CD”-
Automazione: Niente più passaggi manuali o spazio per errori umani. L'intero processo di build, test e deployment può essere automatizzato dall'inizio alla fine.
-
Consistenza: Ogni deployment segue la stessa serie di passaggi, garantendo un processo prevedibile e ripetibile. Questo è particolarmente prezioso quando più membri del team contribuiscono a code.
-
Iterazioni più rapide: Con i deployment automatizzati, puoi rilasciare aggiornamenti più frequentemente e con maggiore sicurezza. Niente più attese per QA manuali o approvazioni di release.
Capgo CLI
Sezione intitolata “Capgo CLI”Il Capgo CLI è la chiave per integrare Capgo nel tuo workflow CI/CD. Fornisce comandi per pubblicare nuove versioni di bundle, gestire i canali e altro ancora.
Il comando più importante per l'integrazione CI/CD è bundle upload:
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEYSe utilizzi la crittografia, devi fornirla in uno di questi modi:
Utilizzando il percorso di un file di chiave privata:
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATHUtilizzando direttamente il contenuto della chiave privata (consigliato per CI/CD):
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENTUtilizzando variabili d'ambiente (best practice per CI/CD):
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"Configurazione delle variabili d'ambiente per la crittografia
Sezione intitolata “Configurazione delle variabili d'ambiente per la crittografia”Per gli ambienti CI/CD, si consiglia di salvare la chiave privata come variabile d'ambiente invece che in un file. Ecco come configurarla:
-
Ottieni il contenuto della tua chiave privata:
Finestra del terminale cat .capgo_key_v2 | pbcopyQuesto copia il contenuto della chiave negli appunti.
-
Aggiungila al tuo ambiente CI/CD:
- Azioni GitHub: Aggiungi
CAPGO_PRIVATE_KEYai segreti del repository - GitLab CI: Aggiungilo come variabile mascherata nelle impostazioni del progetto
- CircleCI: Aggiungilo come variabile d'ambiente nelle impostazioni del progetto
- Jenkins: Aggiungilo come credenziale di tipo secret text
- Azioni GitHub: Aggiungi
-
Usalo nella tua pipeline:
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"
Nota: Il --key-data-v2 flag ti permette di passare il contenuto della chiave privata direttamente come stringa, ideale per le variabili d'ambiente nelle pipeline CI/CD dove non vuoi creare file temporanei.
Questo comando effettua l'upload della web build corrente sul canale specificato. Di solito lo esegui come ultimo step della pipeline CI/CD, dopo che la web build è stata completata con successo.
Configurazione di Capgo nella tua pipeline CI/CD
Sezione intitolata “Configurazione di Capgo nella tua pipeline CI/CD”Anche se i passaggi esatti variano in base allo strumento CI/CD scelto, il processo generale per integrare Capgo è il seguente:
-
Genera una chiave API: Accedi alla dashboard di Capgo e crea una nuova chiave API. Questa chiave servirà per autenticare CLI nel tuo ambiente CI/CD. Mantienila segreta e non committarla mai nel repository!
-
Configura il
bundle uploadcomando: Aggiungi uno step alla tua configurazione CI/CD che esegua ilbundle uploadcomando con gli argomenti appropriati:\n Sostituisciupload.yml - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}Productioncon il canale su cui vuoi fare il deploy,${{ secrets.CAPGO_API_KEY }}con la variabile d'ambiente che contiene la tua chiave API, e aggiungi--key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"se utilizzi la crittografia. -
Aggiungi la
uploadpassaggio dopo la build web: Assicurati che louploadpassaggio avvenga dopo il completamento della build web. Questo garantisce che tu stia sempre distribuendo l'ultima versione di code.\nEcco un esempio di configurazione per GitHub Actions:\nupload.yml name: Deploy to Capgoon:push:branches: [main]jobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v6- uses: actions/setup-node@v6with:node-version: '24'- run: npm ci- run: npm run build- run: npm install -g @capgo/cli- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"
Gestione delle versioni con Semantic-release
Sezione intitolata “Gestione delle versioni con Semantic-release”Il modo consigliato per gestire il versionamento con Capgo è impostare la versione nel tuo capacitor.config.ts file importandola da package.json:
import pkg from './package.json'
const config: CapacitorConfig = { // ... other config plugins: { CapacitorUpdater: { version: pkg.version, } }}Questo approccio ti permette di:
- Usare semantic-release (o qualsiasi altro tool) per aggiornare la
package.jsoninstallata - Buildare l'app con la versione aggiornata inclusa automaticamente
- Fare l'upload del bundle con la versione corretta
Il tuo workflow CI/CD sarà simile a questo:
- run: npm ci- run: npx semantic-release # Updates package.json version- run: npm run build # Builds with new version from capacitor.config- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}Ecco un esempio di .releaserc file di configurazione per semantic-release:
{ "branches": [ "main", { "name": "beta", "prerelease": true } ], "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/changelog", [ "@semantic-release/git", { "assets": ["CHANGELOG.md", "package.json"], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" } ] ]}Questa configurazione fa quanto segue:
- Analizza i messaggi di commit per determinare il prossimo numero di versione, seguendo la specifica Conventional Commits.
- Genera le release notes basandosi sui commit effettuati dall'ultimo rilascio.
- Aggiorna il
CHANGELOG.mdfile con le nuove release notes. - Aggiorna il
package.jsonversione, che verrà rilevata dalla tua capacitor.config. - Esegue il commit del
CHANGELOG.md,package.jsonfile aggiornato e di tutti gli altri file modificati nel repository.
Assicurati di eseguire semantic-release prima di buildare l'app, così che la versione aggiornata da package.json sia inclusa nella tua build tramite il file capacitor.config.
Auto-bump quando la versione locale è già su Capgo
Sezione intitolata “Auto-bump quando la versione locale è già su Capgo”I nomi dei bundle devono essere univoci (le versioni eliminate occupano comunque il nome). Se la CI continua a caricare la stessa package.json versione, l'upload fallisce. Meglio incrementare package.json (ad esempio con semantic-release). Se non è praticabile, lascia che CLI scelga il prossimo semver libero dal bundle collegato al canale, o l'ultima versione remota dell'app:
npx @capgo/cli@latest bundle upload --channel=production --auto-bumpnpx @capgo/cli@latest bundle upload --auto-bump majornpx @capgo/cli@latest bundle upload --auto-bump minor # default when the flag has no valuenpx @capgo/cli@latest bundle upload --auto-bump patch # alias: fixnpx @capgo/cli@latest bundle upload --auto-bump metadatanpx @capgo/cli@latest bundle upload --channel=production --auto-bump ai--auto-bump ai usa Capgo Cloudflare Workers AI per confrontare i file del bundle locale con i file delta precedenti di Capgo/channel, scegliere major | minor | patch | metadatae stampare una breve motivazione. In assenza di una versione Capgo precedente, l'AI viene saltata e l'incremento è patch.
Non combinare --auto-bump con --bundle / -b. Vedi la bundle upload riferimento per l'elenco completo delle opzioni.
Risoluzione problemi
Sezione intitolata “Troubleshooting”Se riscontri problemi con l'integrazione CI/CD di Capgo, ecco alcune cose da controllare:
-
Chiave API: Assicurati che la tua chiave API sia valida e abbia i permessi necessari. Se usi una variabile d'ambiente, controlla che sia impostata correttamente.
-
Versione CLI: Assicurati di usare l'ultima versione di Capgo CLI. Le versioni precedenti potrebbero avere problemi di compatibilità o non includere alcune funzionalità.
-
Artifact di build: Verifica che la tua web build generi i file di output previsti. Capgo CLI richiede una web build valida per creare un bundle.
-
Connettività di rete: Verifica che il tuo ambiente CI/CD abbia accesso di rete ai server Capgo. Problemi di firewall o proxy possono talvolta interferire con la
uploadcomando.
Se hai ancora problemi, contatta il supporto di Capgo per assistenza. Possono aiutarti a risolvere eventuali problemi con la tua configurazione specifica.
Conclusione
Sezione intitolata “Conclusione”Integrare Capgo nella tua pipeline CI/CD con una gestione corretta delle versioni può semplificare notevolmente il tuo workflow di sviluppo. Automatizzando i deploy e il versioning tramite l'approccio capacitor.config, potrai rilasciare aggiornamenti più rapidamente e con maggiore sicurezza.
L'approccio consigliato di impostare la versione nel tuo capacitor.config.ts file e usare semantic-release per aggiornare package.json garantisce un processo di deployment robusto e affidabile, permettendoti di concentrarti sulla creazione di nuove feature invece di preoccuparti dei passaggi manuali di rilascio.
Per maggiori dettagli sui comandi e le opzioni di Capgo CLI, consulta la documentazione di CLI. E per approfondire la configurazione di semantic-release, leggi la documentazione di semantic-release.
Buon deploy!
Continua dall'integrazione CI/CD
Sezione intitolata “Continua da Integrazione CI/CD”Se stai usando Integrazione CI/CD per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration, e Integrazione GitLab CI/CD per i dettagli sull'implementazione nell'integrazione GitLab CI/CD.