Integrazione CI/CD

Integrare Capgo nella tua pipeline CI/CD ti permette di automatizzare completamente il processo di build e deployment degli update della tua app. Sfruttando Capgo CLI e semantic-release, puoi garantire deployment consistenti e affidabili, accelerando i cicli di iterazione.

Vantaggi dell'integrazione CI/CD

• Automazione: Niente più passaggi manuali o rischio di errori umani. L'intero processo di build, test e deployment può essere automatizzato end-to-end.

• Coerenza: Ogni deployment segue lo stesso flusso, garantendo un processo prevedibile e ripetibile. Fondamentale quando più membri del team contribuiscono a code.

• Iterazioni più rapide: Con i deployment automatizzati, puoi rilasciare aggiornamenti più spesso e con sicurezza. Niente più attese per QA manuali o approvazioni di rilascio.

Capgo CLI

Il Capgo CLI è la chiave per integrare Capgo nel tuo workflow CI/CD. Offre comandi per pushare nuove versioni di bundle, gestire i channel e molto altro.

Il comando più importante per l'integrazione CI/CD è bundle upload:

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

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

Indicando il percorso del file della chiave privata:

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

Inserendo 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_CONTENT

Utilizzando le 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

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:

   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 dell'attuale web build sul canale specificato. Solitamente viene eseguito come ultimo step della pipeline CI/CD, dopo il completamento della web build.

Configurazione di Capgo nella tua pipeline CI/CD

Sebbene i passaggi esatti varino 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 channel 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 lo upload step dopo il tuo web build: Assicurati che lo upload step avvenga dopo il completamento del web build. 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 }}"

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:

1. Usare semantic-release (o altri tool) per aggiornare la package.json versione
2. Buildare l'app includendo automaticamente la nuova versione
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 esegue quanto segue:

1. Analizza i commit per determinare il prossimo numero di versione, seguendo lo spec Conventional Commits.
2. Genera le release notes basandosi sui commit effettuati dall'ultimo rilascio.
3. Aggiorna la CHANGELOG.md con le nuove release notes.
4. Aggiorna la package.json versione, che verrà rilevata dalla tua capacitor.config.
5. Effettua il commit della CHANGELOG.md, package.jsonaggiornata e di tutti gli altri file modificati nel repository.

Assicurati di eseguire semantic-release prima di buildare l'app, così la nuova versione di package.json verrà inclusa nel build tramite la capacitor.config.

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 version, 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-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 del precedente Capgo/channel, sceglie major | minor | patch | metadatae stampa una breve motivazione. In assenza di una versione Capgo precedente, l'AI viene saltata e l'incremento sarà patch.

Non combinare --auto-bump con --bundle / -b. Vedi la bundle upload reference per l'elenco completo delle opzioni.

Risoluzione problemi

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, verifica che sia impostata correttamente.

• Versione CLI: Assicurati di usare l'ultima versione di Capgo CLI. Le versioni precedenti potrebbero avere problemi di compatibilità o mancare di alcune feature.

• Artifact di build: Conferma che la tua web build stia generando i file di output previsti. La Capgo CLI necessita di una web build valida per creare un bundle.

• Connettività di rete: Verifica che il tuo ambiente CI/CD abbia l'accesso alla rete verso i server Capgo. Firewall o proxy potrebbero 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.

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 deployment!

Continua dall'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 sull'integrazione di GitHub Actions, e Integrazione GitLab CI/CD per i dettagli sull'integrazione di GitLab CI/CD.