Integrazione CI/CD

L'integrazione di Capgo nella tua pipeline CI/CD ti consente di automatizzare completamente il processo di creazione e distribuzione di aggiornamenti per la tua app. Sfruttando il Capgo CLI e semantic-release, puoi garantire deployment coerenti, affidabili e consentire iterazioni rapide.

Vantaggi dell'integrazione CI/CD

• Automazione : Nessun passaggio manuale o spazio per errori umani. Il tuo processo di creazione, test e distribuzione può essere automatizzato da capo a fondo.

• Consistenza : Ogni deployment segue lo stesso set di passaggi, garantendo un processo prevedibile e ripetibile. Ciò è particolarmente utile quando hai più membri del team che contribuiscono a code.

• Iterazioni più rapide : Con le distribuzioni automatizzate, puoi spedire aggiornamenti più frequentemente e con fiducia. Nessun aspettare per la QA manuale o le autorizzazioni di rilascio.

Capgo CLI

Il Capgo CLI è la chiave per integrare Capgo nel tuo workflow CI/CD. Fornisce comandi per l'invio di nuove versioni di bundle, la gestione dei canali e 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 l'encryption dovresti fornirlo in uno dei seguenti modi:

Utilizzando il percorso del file della chiave privata:

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

Utilizzando il contenuto della chiave privata direttamente (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 di ambiente (pratica consigliata per CI/CD):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"

Configurazione delle variabili di ambiente per la crittografia

Per gli ambienti CI/CD, si consiglia di memorizzare la tua chiave privata come variabile di ambiente piuttosto che come file. Ecco come configurarla:

1. Ottieni il contenuto della tua chiave privata:

   cat .capgo_key_v2 | pbcopy

   Questo copia il contenuto della chiave nel portapenne.

2. Aggiungilo all'ambiente CI/CD:

   • GitHub Azioni: Aggiungi CAPGO_PRIVATE_KEY ai segreti del tuo repository
   • GitLab CI: Aggiungilo come variabile mascherata nei tuoi impostazioni del progetto
   • CircleCI: Aggiungilo come variabile di ambiente nelle impostazioni del progetto
   • Jenkins: Aggiungilo come credenziale di testo segreta

3. Utilizzalo 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: La --key-data-v2 flag consente di passare il contenuto della chiave privata direttamente come stringa, rendendola perfetta per le variabili di ambiente nei pipeline CI/CD dove non si desidera creare file temporanei.

Questo comando carica la versione web corrente sul canale specificato. Esegui di solito questo comando come passo finale del tuo pipeline CI/CD, dopo che la versione web è stata completata con successo.

Configurazione di Capgo nel tuo pipeline CI/CD

Mentre i passaggi esatti varieranno a seconda del tuo strumento CI/CD di scelta, il processo generale per l'integrazione di Capgo assomiglia a questo:

1. Genera una chiave API: Accedi al pannello di controllo Capgo e crea una nuova chiave API . Questa chiave verrà utilizzata per autenticare il CLI nel tuo ambiente CI/CD. Tienila segreta e non la commettere mai nel tuo repository!

2. Configura il bundle upload comando: Aggiungi un passo al tuo file di configurazione CI/CD che esegue 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 che desideri distribuire, ${{ secrets.CAPGO_API_KEY }} con la variabile di ambiente che contiene la tua chiave API e aggiungi --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" se si utilizza la crittografia.

3. Aggiungi il upload passo dopo la tua costruzione web: Assicurati che il upload passo venga eseguito dopo che la tua costruzione web sia stata completata con successo. Ciò assicura che sempre stai distribuendo la tua ultima code.\n Ecco 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 la versione con Capgo è impostare la versione nel tuo capacitor.config.ts file importandolo da package.json:

import pkg from './package.json'

const config: CapacitorConfig = {
  // ... other config
  plugins: {
    CapacitorUpdater: {
      version: pkg.version,
    }
  }
}

Questa approccio consente di:

1. Utilizzare semantic-release (o qualsiasi altro strumento) per aggiornare la package.json versione
2. Costruire l'app con la versione aggiornata inclusa automaticamente
3. Caricare il bundle con la versione corretta

Il tuo workflow CI/CD sarebbe 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 file di configurazione di esempio per semantic-release: .releaserc Copia nel portapenne

{
  "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}"
      }
    ]
  ]
}

Analizza i messaggi di commit per determinare il numero di versione successivo, seguendo lo spec del Conventional Commits.

1. Genera note di rilascio in base ai commit effettuati dalla versione precedente.
2. Aggiorna il
3. file con le nuove note di rilascio. CHANGELOG.md Aggiorna il
4. numero di versione, che verrà rilevato dal tuo __CAPGO_KEEP_0__.config. package.json version, which will be picked up by your capacitor.config.
5. e di eventuali altri file modificati nel repository. CHANGELOG.md, package.jsonCommette gli aggiornamenti del file e di eventuali altri file modificati nel repository.

Assicurarsi di eseguire semantic-release prima di costruire l'applicazione, in modo che la versione aggiornata da package.json sia inclusa nel build attraverso il capacitor.config.

Aggiorna automaticamente quando la versione locale è già su Capgo

I nomi dei pacchetti devono essere unici (le versioni cancellate occupano ancora il loro nome). Se il CI continua a caricare la stessa package.json versione, il caricamento fallisce. Preferire l'aggiornamento package.json (ad esempio con semantic-release). Quando ciò non è pratico, lasciare che il CLI sceglia la prossima versione semver libera dal canale collegato al pacchetto, o altrimenti la versione app app remota più recente:

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 utilizza Capgo Cloudflare Workers AI per confrontare i file dei pacchetti locali contro il manifesto delta precedente Capgo/canale, scegli major | minor | patch | metadata, e stampa una breve ragione. Senza versione precedente Capgo, l'AI è saltata e l'aggiornamento è patch.

Non combinare --auto-bump con --bundle / -b. Consulta la bundle upload sezione di riferimento per la lista completa delle opzioni.

Sezione intitolata “Risolvere i problemi”

Capgo chiave

• : Assicurati che la tua API chiave sia valida e abbia le autorizzazioni necessarie. Se utilizzi una variabile di ambiente, controlla che sia impostata correttamente.API versione

• : Assicurati di utilizzare la versione più recente del tuo CLI __CAPGO_KEEP_1__. Le versioni più vecchie possono avere problemi di compatibilità o mancare di alcune funzionalità.: Make sure you’re using the latest version of the Capgo CLI. Older versions may have compatibility issues or lack certain features.

• Articoli di costruzione: Assicurati che la tua costruzione web generi i file di output previsti. I Capgo CLI richiedono una costruzione web valida per creare un bundle.

• Connettività di rete: Controlla che il tuo ambiente CI/CD abbia accesso alla rete ai server Capgo. Problemi di firewall o proxy possono interferire con la upload comando.

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

Conclusioni

L'integrazione di Capgo nel tuo pipeline CI/CD con una gestione delle versioni corretta può notevolmente semplificare il tuo workflow di sviluppo. Automatizzando le tue distribuzioni e le versioni attraverso l'approccio capacitor.config, puoi spedire aggiornamenti più velocemente e con maggiore fiducia.

L'approccio consigliato di impostare la versione nel tuo capacitor.config.ts file e utilizzare semantic-release per aggiornare package.json fornisce un processo di distribuzione robusto e affidabile che ti consente di concentrarti sulla creazione di grandi funzionalità piuttosto che preoccuparti dei passaggi di rilascio manuali.

Per ulteriori informazioni sui comandi e le opzioni Capgo CLI , consultare il CLI riferimento. E per una visione più approfondita della configurazione di semantic-release, vedere i docs di semantic-release.

Buon deploy!

Continua dall'Integrazione CI/CD

Se stai utilizzando Integrazione CI/CD per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, GitHub Actions Integration for the implementation detail in GitHub Actions Integration, and Integrazione CI/CD di GitLab per il dettaglio di implementazione in Integrazione CI/CD di GitLab.