Integrazione CI/CD

Integrando il Capgo nella tua pipeline CI/CD puoi 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.

Benefici 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 distribuzione segue lo stesso set di passaggi, garantendo un processo prevedibile e ripetibile. Ciò è particolarmente utile quando hai più membri del team che contribuiscono al code.

• Iterazioni più rapide: Con le distribuzioni automatizzate, puoi spedire aggiornamenti più frequentemente e con fiducia. Non devi più attendere la verifica manuale o l'approvazione di rilascio.

Capgo CLI

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

La più importante istruzione 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 da uno di questi 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 portapenna.

2. Aggiungilo nel tuo ambiente CI/CD:

   • GitHub Azioni: Aggiungi CAPGO_PRIVATE_KEY a segreto 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 nel tuo 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 flussi CI/CD in cui non si desidera creare file temporanei.

Questo comando carica la versione corrente del build web sul canale specificato. Di solito eseguirai questo come passo finale del tuo flusso CI/CD, dopo che il tuo build web è stato completato con successo.

Configurazione di Capgo nel tuo flusso 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 API chiave: Accedi al dashboard di Capgo e crea una nuova API chiave. 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 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 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 lo step dopo la tua build web upload : Assicurati che lo step venga eseguito dopo che la tua build web sia stata completata con successo. Ciò assicura che stai sempre distribuendo la tua ultima __CAPGO_KEEP_0__.\n Ecco un esempio di configurazione per __CAPGO_KEEP_1__ Actions:\nupload.yml upload step comes after your web build has completed successfully. This ensures you’re always deploying your latest code.\n Here’s an example configuration for GitHub Actions:\n

   Sostituisci con la variabile di ambiente che contiene la tua chiave __CAPGO_KEEP_0__

   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 della versione con Semantic-release

Il modo consigliato per gestire la versioning con Capgo è impostare la versione nel tuo capacitor.config.ts file caricandolo 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'applicazione con la versione aggiornata automaticamente inclusa
3. Caricare il bundle con la versione corretta

La tua pipeline CI/CD sarebbe come questa:

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

1. Analizza i messaggi di commit per determinare il numero di versione successivo, seguendo lo spec del Conventional Commits.
2. Genera note di rilascio in base ai commit effettuati dalla versione precedente.
3. Aggiorna il CHANGELOG.md file con le nuove note di rilascio.
4. Aggiorna il package.json numero di versione, che verrà preso in carico dal tuo capacitor.config.
5. Commette l'aggiornamento CHANGELOG.md, package.jsone di qualsiasi altro file modificato, torna nel repository.

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

Aggiorna automaticamente quando la versione locale è già su Capgo

Il nome del pacchetto deve essere unico (le versioni cancellate occupano ancora il loro nome). Se il CI continua a caricare la stessa package.json versione, il caricamento fallisce. Preferisci l'aggiornamento package.json (ad esempio con semantic-release). Quando ciò non è pratico, lascia che il CLI sceglie 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 del pacchetto locale con il precedente Capgo/canale delta manifesto, scegli major | minor | patch | metadatae stampa una breve ragione. Senza una versione precedente Capgo, l'AI è saltata e l'aggiornamento è patch.

Non combinare --auto-bump con --bundle / -bVedi il bundle upload riferimento per l'elenco delle opzioni complete.

Risoluzione Problemi

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

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

• Versione di CLI: 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: Assicurati che la tua costruzione web generi i file di output previsti. Il Capgo CLI richiede una costruzione web valida per creare un bundle.

• Connessione di rete: Controlla che il tuo ambiente CI/CD abbia accesso a rete ai server Capgo. I problemi di firewall o proxy possono interferire con il 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

Integrare Capgo nel tuo flusso di lavoro di sviluppo con la gestione delle versioni può semplificare notevolmente il tuo workflow. Automatizzando le tue distribuzioni e versionando 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, consulta il riferimento CLI. E per una visione più approfondita della configurazione di semantic-release, consulta i documenti di semantic-release.

! Buon deploy!

Continua da CI/CD Integration

Integrazione CI/CD context: Pagina/Area: Capgo Builder / prodotto di costruzione nativa per pagina cloud. Ruolo: Etichetta di navigazione breve o elemento UI. Chiave messaggio `native_build_feature_ci_cd` (Native Build Feature 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 workflow del prodotto in Capgo Costruzioni native, Capgo Integrazioni per il workflow del prodotto in Capgo Integrazioni, GitHub Integrazione delle azioni per la dettaglio di implementazione in GitHub Integrazione delle azioni, e Integrazione CI/CD di GitLab per la dettaglio di implementazione in Integrazione CI/CD di GitLab.