Vai al contenuto

Integrazione CI/CD

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.

  • 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.

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:

Finestra del terminale
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY

Se utilizzi la crittografia, devi fornirla in uno di questi modi:

Utilizzando il percorso di un file di chiave privata:

Finestra del terminale
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATH

Utilizzando direttamente il contenuto della chiave privata (consigliato per CI/CD):

Finestra del terminale
npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENT

Utilizzando variabili d'ambiente (best practice per CI/CD):

Finestra del terminale
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:

  1. Ottieni il contenuto della tua chiave privata:

    Finestra del terminale
    cat .capgo_key_v2 | pbcopy

    Questo copia il contenuto della chiave negli appunti.

  2. Aggiungila al tuo ambiente CI/CD:

    • Azioni GitHub: Aggiungi CAPGO_PRIVATE_KEY ai 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
  3. 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.

Anche se i passaggi esatti variano in base allo strumento CI/CD scelto, il processo generale per integrare Capgo è il seguente:

  1. 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!

  2. Configura il bundle upload comando: Aggiungi uno step alla tua configurazione CI/CD che esegua il bundle upload comando con gli argomenti appropriati:

    upload.yml
    - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}
    \n Sostituisci Production con 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.

  3. Aggiungi la upload passaggio dopo la build web: Assicurati che lo upload passaggio 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:\n

    upload.yml
    name: Deploy to Capgo
    on:
    push:
    branches: [main]
    jobs:
    deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-node@v6
    with:
    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 }}"

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:

  1. Usare semantic-release (o qualsiasi altro tool) per aggiornare la package.json installata
  2. Buildare l'app con la versione aggiornata inclusa automaticamente
  3. 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:

  1. Analizza i messaggi di commit per determinare il prossimo numero di versione, seguendo la specifica Conventional Commits.
  2. Genera le release notes basandosi sui commit effettuati dall'ultimo rilascio.
  3. Aggiorna il CHANGELOG.md file con le nuove release notes.
  4. Aggiorna il package.json versione, che verrà rilevata dalla tua capacitor.config.
  5. 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:

Finestra del terminale
npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @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.

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 upload comando.

Se hai ancora problemi, contatta il supporto di Capgo per assistenza. Possono aiutarti a risolvere eventuali problemi con la tua configurazione specifica.

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!

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.