Integrazione con GitLab CI/CD

Integrate Capgo Live Updates with GitLab CI/CD to automatically deploy your app updates whenever you push code changes. This guide covers setting up automated builds, testing, and deployment workflows.

Requisiti

Prima di configurare l'integrazione di GitLab CI/CD, assicurati di avere:

• Un account GitLab con un repository di progetto
• Un account Capgo con un'app configurata
• Node.js e npm/yarn configurati nel tuo progetto

Configurazione di GitLab CI/CD

Passo 1: Configura le variabili di ambiente

In primo luogo, configura le variabili necessarie nel tuo progetto GitLab:

1. Naviga nel tuo progetto GitLab
2. Vai a Impostazioni → CI/CD → Variabili
3. Aggiungi le seguenti variabili:

Nome Variabile	Valore	Protetto	Nascosto
CAPGO_TOKEN	Il tuo token Capgo API	✅ Sì	✅ Sì

Suggerimento

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

Elemento semplice

Configurazione base che distribuisce in produzione con ogni push sul ramo principale:

# .gitlab-ci.yml - Simple Configuration
image: node:22

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

build:
  stage: build
  script:
    - npm ci
    - npm run test
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  only:
    - main

deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
    # For encrypted uploads, add: --key-data-v2 "$CAPGO_PRIVATE_KEY"
  dependencies:
    - build
  only:
    - main

Elemento avanzato

Distribuzioni del ramo di feature

Distribuisce i rami di feature nei canali di test per la revisione e il testing:

# Feature branch deployment
deploy_feature:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - CHANNEL_NAME="feature-$(echo $CI_COMMIT_REF_NAME | sed 's/[^a-zA-Z0-9-]/-/g')"
    - npx @capgo/cli channel create $CHANNEL_NAME --apikey $CAPGO_TOKEN || true
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
  dependencies:
    - build
  only:
    - /^feature\/.*$/
  environment:
    name: feature/$CI_COMMIT_REF_NAME
    url: https://your-app.com/channels/$CHANNEL_NAME

Avviso

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

Utilizzo della crittografia

__CAPGO_KEEP_0__'s funzionalità di crittografia Capgo’s encryption featureDopo

l'aggiunta delle chiavi di crittografia localmente, aggiungi la tua chiave privata alle variabili di GitLab: Dopo aver impostato le chiavi di crittografia localmente, aggiungi la tua chiave privata alle variabili di GitLab:

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

Aggiungi questo contenuto come CAPGO_PRIVATE_KEY nel tuo progetto GitLab (segna come protetto e mascherato), quindi utilizzalo nelle pipeline:

# Deploy with encryption
deploy_production:
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --key-data-v2 "$CAPGO_PRIVATE_KEY" --channel production

Attenzione

Pratiche di sicurezza migliori:

• Non commetti mai il .capgo_key_v2 file nel controllo delle versioni
• Mantieni la chiave privata solo nella gestione segreta dei CI/CD
• Utilizza chiavi diverse per ambienti diversi

Configurazione dei Canali Multipli

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

Configurazione completa con più ambienti e distribuzioni di richiesta di merge:

# .gitlab-ci.yml - Advanced Multi-Channel Configuration
image: node:22

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

# Build stage
build:
  stage: build
  script:
    - npm ci
    - npm run test
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 24 hours

# Deploy to development channel
deploy_development:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel development
  dependencies:
    - build
  only:
    - develop
  environment:
    name: development

# Deploy merge requests to test channels
deploy_mr:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - CHANNEL_NAME="mr-$CI_MERGE_REQUEST_IID"
    - npx @capgo/cli channel create $CHANNEL_NAME --apikey $CAPGO_TOKEN || true
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
  dependencies:
    - build
  only:
    - merge_requests
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    url: https://your-app.com/channels/mr-$CI_MERGE_REQUEST_IID
    on_stop: cleanup_mr

# Cleanup MR channels when MR is closed
cleanup_mr:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli channel delete mr-$CI_MERGE_REQUEST_IID --apikey $CAPGO_TOKEN || true
  when: manual
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    action: stop
  only:
    - merge_requests

# Deploy to staging
deploy_staging:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel staging
  dependencies:
    - build
  only:
    - develop
  environment:
    name: staging

# Deploy to production
deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  dependencies:
    - build
  only:
    - main
  environment:
    name: production

Multi-ambiente con approvazione manuale

Per le distribuzioni di produzione che richiedono approvazione manuale:

deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  dependencies:
    - build
  only:
    - main
  when: manual
  environment:
    name: production

Strategia di distribuzione basata sul ramo

Deploya diverse rami in canali appropriati automaticamente:

# Dynamic channel deployment based on branch
deploy:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - |
      if [ "$CI_COMMIT_REF_NAME" = "main" ]; then
        CHANNEL="production"
      elif [ "$CI_COMMIT_REF_NAME" = "develop" ]; then
        CHANNEL="staging"
      else
        CHANNEL="development"
      fi
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL
  dependencies:
    - build
  environment:
    name: $CHANNEL

Pratiche di Sicurezza Migliorate

Variabili Protette

1. Segnala Variabili Sensibili: Segna sempre i token API come protetti e mascherati
2. Protezione del Ramo: Utilizza variabili protette per le distribuzioni di produzione
3. Controllo dell'Accesso: Limita l'accesso alle variabili ai soli mantenitori
4. Rotazione regolare: Ruota i token API regolarmente

Configurazione della pipeline sicura

# Use protected variables for production
deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  only:
    refs:
      - main
    variables:
      - $CI_COMMIT_REF_PROTECTED == "true"

Monitoraggio e notifiche

Integrazione con Slack

Aggiungi notifiche di Slack alla tua pipeline:

notify_success:
  stage: .post
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - |
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"✅ Capgo deployment successful for '"$CI_COMMIT_REF_NAME"'"}' \
        $SLACK_WEBHOOK_URL
  when: on_success

notify_failure:
  stage: .post
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - |
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"❌ Capgo deployment failed for '"$CI_COMMIT_REF_NAME"'"}' \
        $SLACK_WEBHOOK_URL
  when: on_failure

Notifiche via e-mail

Configura le notifiche via email nei impostazioni del tuo progetto GitLab o utilizza il API

notify_email:
  stage: .post
  script:
    - |
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
        --form "to=team@yourcompany.com" \
        --form "subject=Capgo Deployment Status" \
        --form "body=Deployment of $CI_COMMIT_REF_NAME completed with status: $CI_JOB_STATUS" \
        "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/emails"
  when: always

Risoluzione dei problemi

Problemi comuni

Il flusso di lavoro fallisce con “Capgo CLI non trovato”:

# Debug CLI installation
debug_cli:
  script:
    - npm install -g @capgo/cli
    - which capgo || echo "Capgo CLI not found"
    - npx @capgo/cli --version

Errori di autenticazione:

# Verify token configuration
debug_auth:
  script:
    - |
      if [ -z "$CAPGO_TOKEN" ]; then
        echo "CAPGO_TOKEN is not set"
        exit 1
      fi
      echo "Token length: ${#CAPGO_TOKEN}"

I file di output non sono stati trovati:

# List build outputs
debug_build:
  script:
    - ls -la dist/
    - find dist/ -type f -name "*.js" -o -name "*.html"

Pipeline di debug

Aggiungi informazioni di debug per risolvere problemi:

debug:
  stage: build
  script:
    - echo "Branch: $CI_COMMIT_REF_NAME"
    - echo "Commit: $CI_COMMIT_SHA"
    - echo "Build: $CI_PIPELINE_ID"
    - env | grep CI_ | sort
  only:
    - branches

Passaggi successivi

• Scopri Canali per gestire diversi ambienti di distribuzione
• Esplora Archiviazione personalizzata 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 GitLab CI/CD, puoi automatizzare i tuoi Capgo deployment e assicurarti aggiornamenti coerenti e affidabili per i tuoi utenti di app mobili.

Continua da qui: Integrazione di GitLab CI/CD

Se stai utilizzando Integrazione di GitLab CI/CD 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 il dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione delle azioni per il dettaglio di implementazione in GitHub Integrazione delle azioni.