Integrazione CI/CD

La 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 distribuzioni coerenti e affidabili e abilitare l'iterazione rapida.

Benefici dell'integrazione CI/CD

• AutomazioneNo più passaggi manuali o spazio per errori umani. Il tuo processo di costruzione, test e distribuzione può essere automatizzato da fine a fine.

• Consistenza: Every deployment follows the same set of steps, ensuring a predictable and repeatable process. This is especially valuable when you have multiple team members contributing code.

• Iterazioni più velociCon le distribuzioni automatizzate, puoi spedire aggiornamenti più frequentemente e con fiducia. Non devi più aspettare la QA manuale o le autorizzazioni di rilascio.

Capgo CLI

The Capgo CLI is the key to integrating Capgo into your CI/CD workflow. It provides commands for pushing new bundle versions, managing channels, and more.

La comanda 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 di questi modi:

Utilizzando un 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 migliore 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

In 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 nella tua clipboard.

2. Aggiungilo all'ambiente CI/CD:

   • GitHub Azioni: Aggiungi CAPGO_PRIVATE_KEY a segreti del tuo repository
   • GitLab CI: Aggiungilo come variabile mascherata nelle impostazioni del tuo progetto
   • CircleCI: Aggiungilo come variabile di ambiente nelle impostazioni del tuo 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 bandiera consente di passare il contenuto della chiave privata direttamente come stringa, rendendola perfetta per le variabili di ambiente nei pipeline CI/CD in cui non si desidera creare file temporanei.

Questo comando carica la versione web corrente nel canale specificato. Di solito eseguirai questo comando come ultimo passo nella tua pipeline CI/CD, dopo che la tua versione web è stata completata con successo.

Configurazione di Capgo nella tua pipeline CI/CD

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

1. Genera una chiave API: Accedi al dashboard 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 passaggio alla tua 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 }}

   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 l'encryption.

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 di sempre distribuire la tua versione più recente 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 versioning con Capgo è impostare la versione nel tuo capacitor.config.ts importarlo dal file 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 il package.json Versione
2. Costruisci l'app con la versione aggiornata inclusa automaticamente
3. Carica il bundle con la versione corretta

La tua pipeline CI/CD dovrebbe avere questo aspetto:

- 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 .releaserc di 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 le seguenti cose:

1. Analizza i messaggi di commit per determinare il numero di versione successivo, seguendo lo spec di Conventional Commits.
2. Genera note di rilascio basate sui commit dallo scorso rilascio.
3. Aggiorna il CHANGELOG.md file con le note della nuova versione.
4. Aggiorna il package.json la versione, che verrà presa in carico dal tuo capacitor.config.
5. Committi l'aggiornamento del CHANGELOG.md, package.jsone di qualsiasi altro file modificato, nel repository.

Assicurati di eseguire semantic-release prima di costruire l'app, in modo che la versione aggiornata da package.json venga inclusa nella tua build attraverso il capacitor.config.

Auto-bump quando la versione locale è già su Capgo

I nomi dei bundle devono essere unici (le versioni eliminate occupano ancora il loro nome). Se il CI continua a caricare lo stesso package.json versione, il caricamento fallisce. Preferisci l'incremento package.json (ad esempio con semantic-release). Quando ciò non è pratico, lascia che il CLI prenda la prossima versione semver libera dal bundle collegato del canale, o altrimenti la versione app più recente remota:

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 del pacchetto locale con i precedenti Capgo/delta dei canali, scegli major | minor | patch | metadata, e stampa una breve ragione. Senza una versione precedente Capgo, l'AI è saltata e il bump è patch.

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

Risolvere i problemi

Se incontri problemi con l'integrazione CI/CD del tuo Capgo, ecco alcune cose da controllare:

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

• CLI versione: Assicurati di utilizzare la versione più recente del Capgo CLI. Le versioni più vecchie possono avere problemi di compatibilità o mancare di alcune funzionalità.

• Articoli di costruzione: Conferma che il tuo build web genera i file di output previsti. Il Capgo CLI richiede un build web valido per creare un bundle.

• Connettività di rete: Controlla che l'ambiente CI/CD abbia accesso alla rete ai server Capgo. I problemi di firewall o proxy possono interferire con il comando. upload command.

Se hai ancora difficoltà, contattare il supporto Capgo per ricevere assistenza. Possono aiutarti a risolvere eventuali problemi con la tua configurazione specifica.

Conclusion

Integrare il Capgo nella tua 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.

La raccomandata impostazione di versione nel tuo capacitor.config.ts file e l'utilizzo di semantic-release per l'aggiornamento 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, consulta la documentazione di riferimento CLIe per una visione più approfondita della configurazione di semantic-release, consulta i docs di semantic-release.

Buon deploy!

Continua da qui: CI/CD Integration

Se stai utilizzando Integrazione CI/CD per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il workflow del prodotto in Capgo CI/CD, Capgo Costruzioni native per il flusso di lavoro del prodotto in Capgo Costruzioni native, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, GitHub Integrazione azioni per i dettagli di implementazione in GitHub Integrazione azioni, e Integrazione CI/CD di GitLab per i dettagli di implementazione in GitLab CI/CD Integration.