Integrazione con GitLab CI/CD

Integra le Capgo Aggiornamenti in Tempo Reale con GitLab CI/CD per automatizzare i deploy del tuo app ogni volta che puoi code modifiche. Questa guida copre la configurazione delle build automatizzate, dei test e dei workflow di distribuzione.

Requisiti

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

• Un account di GitLab con un repository di progetto
• Un Capgo account 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

Prima, impostare 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 Capgo API token	✅ Sì	✅ Sì

Suggerimento

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

Configurazione semplice

Configurazione base che distribuisce in produzione con ogni push al branch 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

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 CanaliDopo 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, avrai bisogno di 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 di 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 migliore:

• Non commettere mai il .capgo_key_v2 file in controllo di versione
• Mantieni 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 sulle impostazioni e la gestione di più canali di distribuzione, consulta la documentazione dei 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

Distribuisci 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 Rama: Utilizza variabili protette per le distribuzioni 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 pipeline 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}"

Non trovati artefatti di costruzione:

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

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

Continua da qui dall'integrazione di GitLab CI/CD

Se stai utilizzando L'integrazione di GitLab CI/CD per pianificare l'automazione CI/CD, collegala con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Builds nativi per il flusso di lavoro del prodotto in Capgo Builds nativi Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per la dettaglio di implementazione in Integrazione CI/CD, e GitHub Integrazione Azioni per la dettaglio di implementazione in GitHub Integrazione Azioni.