Integrazione CI/CD di GitLab

Integra gli aggiornamenti in tempo reale Capgo con GitLab CI/CD per distribuire automaticamente gli aggiornamenti del tuo app ogni volta che puoi spingere code modifiche. Questa guida copre la configurazione delle pipeline di costruzione automatica, testing e deployment.

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 al tuo progetto GitLab
2. Vai a Impostazioni → CI/CD → Variabili
3. Aggiungi le seguenti variabili:

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

Consiglio

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

Configurazione semplice che distribuisce in produzione con ogni push al ramo principale:

Sezione intitolata “Semplice”

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

Avanzato

Distribuzioni di Branch di Feature

Distribuisci le branch 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

Suggerimento

Testing con Canali : Dopo aver distribuito in un canale di feature, 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

Se stai utilizzando Capgo's funzionalità di crittografia, dovrai memorizzare la tua chiave privata in modo sicuro nel tuo ambiente CI/CD.

Dopo l'installazione delle 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 nelle tue variabili del progetto GitLab (segna come protette e mascherate), 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 commettere mai il .capgo_key_v2 file in controllo di versione
• Conserva la chiave privata solo in un gestore di segreti di CI/CD sicuro
• Usa chiavi diverse per ambienti diversi

Configurazione di canali multipli

Per informazioni complete sulle impostazioni e la gestione di più canali di distribuzione, consulta la documentazione sui Canali.

Configurazione completa con più ambienti e deployment 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 deployment 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 deployment basata sul ramo

Deployare rami diversi nei 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 migliori

Variabili Protette

1. Segnala Variabili Sensitive: Segnala sempre i token API come protetti e mascherati
2. Protezione della Branch: Utilizza le variabili protette per i deployment di produzione
3. Controllo dell'Accesso: Limita l'accesso alle variabili ai soli mantenitori
4. Rotazione Regolare: Ruota regolarmente i token API

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 Slack

Aggiungi notifiche Slack al tuo 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 Email

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

Articoli di costruzione non trovati:

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

Flusso di lavoro di debug

Aggiungi informazioni di debug per risolvere i 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 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 GitLab CI/CD, puoi automatizzare i tuoi Capgo deployment e assicurarti aggiornamenti coerenti e affidabili per i tuoi utenti di app mobili.