Integrazione delle azioni di GitHub

Integra gli aggiornamenti in tempo reale di Capgo con le azioni di GitHub per distribuire automaticamente gli aggiornamenti del tuo app ogni volta che pubblichi code modifiche. Questa guida copre la configurazione di costruzioni automatizzate, test e workflow di distribuzione utilizzando la potente piattaforma CI/CD di GitHub.

Prerequisiti

Prima di configurare l'integrazione delle azioni di GitHub, assicurati di avere:

• A GitHub repository with your app’s source code
• Un account Capgo con un'app configurata
• Node.js e npm/yarn configurati nel tuo progetto
• Gli azioni di GitHub abilitati per il tuo repository

Configurazione dei segreti GitHub

Passo 1: Configura i segreti del repository

Configura i segreti necessari nel tuo repository GitHub:

1. Naviga nel tuo repository GitHub
2. Vai a Impostazioni → Segreti e variabili → Azioni
3. Clicca Crea un nuovo segreto del repository e aggiungi il seguente:

Nome segreto	Valore
CAPGO_TOKEN	il tuo token Capgo API

Suggerimento

Otterra il tuo token Capgo API da console.capgo.app/apikeys. Il tuo ID app è già configurato nel tuo capacitor.config.ts file.

Deployamento di produzione semplice

Inizia con questa configurazione base che distribuisce in produzione con ogni push al ramo principale:

# Simple GitHub Actions Workflow for Capgo Live Updates
name: Deploy to Capgo

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install, test and build
        run: |
          npm ci
          npm run test
          npm run build

      - name: Deploy to Capgo
         run: |
           npm install -g @capgo/cli
           npx @capgo/cli bundle upload --channel production
          env:
            CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
           # For encrypted uploads, add: --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Configurazione avanzata di canali multipli

Distribuzioni di rami di feature

Distribuisci i rami di feature in canali temporanei per il testing:

# Feature branch deployment
name: Deploy Feature Branch to Capgo

on:
  push:
    branches:
      - 'feature/**'

jobs:
  deploy-feature:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: |
          npm ci
          npm run test
          npm run build

      - name: Deploy to feature channel
        run: |
          CHANNEL_NAME=$(echo "${{ github.ref_name }}" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
          npm install -g @capgo/cli
          npx @capgo/cli channel create $CHANNEL_NAME --apikey ${{ secrets.CAPGO_TOKEN }} || true
                     npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel $CHANNEL_NAME

Utilizzo della crittografia

Se stai utilizzando la funzione di crittografia di __CAPGO_KEEP_0__ Capgo’s encryption featurePer poter utilizzare la tua chiave privata, devi archiviarla in modo sicuro nel tuo ambiente CI/CD.

Dopo avere configurato le chiavi di cifratura localmente, aggiungi la tua chiave privata ai segreti di GitHub:

# Display your private key content (copy this output)
cat .capgo_key_v2

Aggiungi questo contenuto come CAPGO_PRIVATE_KEY nel tuo repository GitHub segreti, quindi utilizzalo nelle workflow:

# Deploy with encryption
- name: Deploy to Capgo with Encryption
  run: |
    npm install -g @capgo/cli
    npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" --channel production

Attenzione

Pratiche di sicurezza migliori:

• Non mai committare il .capgo_key_v2 file al controllo delle versioni
• Memorizza la chiave privata solo in un gestore di segreti di CI/CD sicuro
• Usa chiavi diverse per ambienti diversi

Configurazione Multi-Canale

Per informazioni complete sulla configurazione e gestione di più canali di distribuzione, consulta la documentazione sui canali.

Flusso completo con sviluppo, richieste di pull e distribuzioni di produzione:

# Complete multi-environment workflow
name: Deploy to Capgo

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: |
          npm ci
          npm run test
          npm run build

      - uses: actions/upload-artifact@v6
        with:
          name: dist
          path: dist/

  deploy-development:
    if: github.ref == 'refs/heads/develop'
    needs: build
    runs-on: ubuntu-latest
    environment: development
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - run: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel development

  deploy-pr:
    if: github.event_name == 'pull_request'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - name: Deploy to PR channel
        run: |
          CHANNEL_NAME="pr-${{ github.event.number }}"
          npm install -g @capgo/cli
          npx @capgo/cli channel create $CHANNEL_NAME --apikey ${{ secrets.CAPGO_TOKEN }} || true
          npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel $CHANNEL_NAME

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `🚀 This PR has been deployed to Capgo channel: \`pr-${{ github.event.number }}\`\n\nTo test this update in your app, configure it to use this channel. [Learn how to configure channels →](/docs/live-updates/channels/#configuring-the-channel-in-your-app)`
            })

  deploy-production:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/

      - run: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload --apikey ${{ secrets.CAPGO_TOKEN }} --channel production

Suggerimento

Testare con i canali: Dopo aver distribuito in un canale PR o di sviluppo, puoi testare l'aggiornamento nell'applicazione configurandola per utilizzare quel canale specifico. Scopri di più su la configurazione dei canali nell'applicazione.

Pulizia dei canali dei feature

Pulisci automaticamente i canali dei feature quando vengono eliminate le branch:

name: Cleanup Feature Channels

on:
  delete:

jobs:
  cleanup:
    runs-on: ubuntu-latest
    if: github.event.ref_type == 'branch' && startsWith(github.event.ref, 'feature/')
    steps:
      - uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Delete Capgo channel
        run: |
          CHANNEL_NAME=$(echo "${{ github.event.ref }}" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
          npm install -g @capgo/cli
          npx @capgo/cli channel delete $CHANNEL_NAME --apikey ${{ secrets.CAPGO_TOKEN }} || true

Security e Pratiche Migliori

Regole di protezione dell'ambiente

Configura le regole di protezione dell'ambiente in GitHub:

1. Vai a Impostazioni → Ambienti nel tuo repository
2. Creare ambienti: development, staging, production
3. Per ambiente di produzione, aggiungi:
   • Richiedi approvazione: Aggiungi membri del team che devono approvare i deployment
   • Timer di attesa: Aggiungi un ritardo prima del deployment (facoltativo)
   • Branch di deployment: Limita a main solo branch

Gestione dei segreti sicura

Usa segreti specifici per ambiente:

# Use different secrets per environment
deploy-production:
  environment: production
  steps:
    - name: Deploy to Production
      run: |
        npx @capgo/cli bundle upload \
          --apikey ${{ secrets.CAPGO_PROD_TOKEN }} \
          --app ${{ secrets.CAPGO_PROD_APP_ID }} \
          --channel production

Monitoraggio e Notifiche

Integrazione Slack

Aggiungi notifiche Slack al tuo workflow:

name: Deploy with Notifications

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # ... deployment steps

      - name: Notify Slack on Success
        if: success()
        uses: 8398a7/action-slack@v3
        with:
          status: success
          text: '✅ Capgo deployment successful!'
          fields: repo,message,commit,author,action,eventName,ref,workflow
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

      - name: Notify Slack on Failure
        if: failure()
        uses: 8398a7/action-slack@v3
        with:
          status: failure
          text: '❌ Capgo deployment failed!'
          fields: repo,message,commit,author,action,eventName,ref,workflow
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Integrazione Discord

Invia notifiche a Discord:

- name: Discord notification
  if: always()
  uses: Ilshidur/action-discord@master
  with:
    args: |
      Capgo deployment ${{ job.status }}!
      App: ${{ secrets.CAPGO_APP_ID }}
      Channel: ${{ github.ref_name }}
      Commit: ${{ github.sha }}
  env:
    DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}

Notifiche via Email

Configura le notifiche via email:

- name: Send email notification
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: 'Capgo Deployment Failed - ${{ github.repository }}'
    to: team@yourcompany.com
    from: ci-cd@yourcompany.com
    body: |
      Deployment failed for ${{ github.repository }}
      Branch: ${{ github.ref_name }}
      Commit: ${{ github.sha }}
      Workflow: ${{ github.workflow }}

Risoluzione dei Problemi

Flusso di Debugging

Aggiungi passaggi di debug per risolvere i problemi:

- name: Debug environment
  run: |
    echo "Node version: $(node --version)"
    echo "NPM version: $(npm --version)"
    echo "Working directory: $(pwd)"
    echo "Files in dist/: $(ls -la dist/ || echo 'No dist directory')"
    echo "Environment variables:"
    env | grep -E "(GITHUB_|CAPGO_)" | sort

- name: Test Capgo CLI
  run: |
    npx @capgo/cli --version
    npx @capgo/cli app debug --apikey ${{ secrets.CAPGO_TOKEN }} --app ${{ secrets.CAPGO_APP_ID }}

Problemi comuni e soluzioni

Il flusso di lavoro fallisce con “CAPGO_TOKEN not found”:

- name: Verify secrets
  run: |
    if [ -z "${{ secrets.CAPGO_TOKEN }}" ]; then
      echo "ERROR: CAPGO_TOKEN secret is not set"
      exit 1
    fi
    echo "CAPGO_TOKEN is set (length: ${#CAPGO_TOKEN})"
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Non trovati artefatti di costruzione:

- name: Debug artifacts
  run: |
    echo "Checking for build artifacts..."
    ls -la dist/ || echo "No dist directory found"
    find . -name "*.js" -o -name "*.html" | head -10

Problemi di connettività di rete:

- name: Test connectivity
  run: |
    ping -c 3 api.capgo.io || echo "Ping failed"
    curl -I https://api.capgo.io/health || echo "Health check failed"

Flussi di lavoro riutilizzabili

Crea flussi di lavoro riutilizzabili per una consistenza across progetti:

github/workflow riciclabili/reutilizzabile-capgo-deploy.yml

name: Reusable Capgo Deploy

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      channel:
        required: true
        type: string
    secrets:
      CAPGO_TOKEN:
        required: true
      CAPGO_APP_ID:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Deploy to Capgo
        run: |
          npm install -g @capgo/cli
          npx @capgo/cli bundle upload \
            --apikey ${{ secrets.CAPGO_TOKEN }} \
            --app ${{ secrets.CAPGO_APP_ID }} \
            --channel ${{ inputs.channel }}

Usa il workflow riciclabile:

github/workflow deploy.yml

name: Deploy App

on:
  push:
    branches: [main, develop]

jobs:
  deploy-dev:
    if: github.ref == 'refs/heads/develop'
    uses: ./.github/workflows/reusable-capgo-deploy.yml
    with:
      environment: development
      channel: development
    secrets:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
      CAPGO_APP_ID: ${{ secrets.CAPGO_APP_ID }}

  deploy-prod:
    if: github.ref == 'refs/heads/main'
    uses: ./.github/workflows/reusable-capgo-deploy.yml
    with:
      environment: production
      channel: production
    secrets:
      CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
      CAPGO_APP_ID: ${{ secrets.CAPGO_APP_ID }}

Passaggi successivi

• Scopri Canali per gestire ambienti di distribuzione diversi
• Esplora Storage personalizzato per scenari di distribuzione avanzati
• Configura Crittografia per distribuzioni sicure
• Configura Aggiorna il comportamento per personalizzare come vengono applicate le aggiornamenti

Con l'integrazione di GitHub Actions, puoi sfruttare le potenti funzionalità del piattaforma CI/CD di GitHub per creare complessi workflow di distribuzione con funzionalità di sicurezza, monitoraggio e collaborazione integrate per le tue Capgo Live Updates.

Continua da GitHub Actions Integration

Se stai utilizzando GitHub Actions Integration per pianificare l'automazione CI/CD, connettilo con Capgo automazione CI/CD per il flusso di lavoro del prodotto in Capgo automazione 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, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e Integrazione CI/CD di GitLab per i dettagli di implementazione in Integrazione CI/CD di GitLab.