GitLab CI/CD-Integration

Integriere Capgo Live Updates mit GitLab CI/CD, um Ihre App-Updates automatisch zu deployen, sobald Sie code Änderungen pushen. Diese Anleitung behandelt die Einrichtung automatischer Builds, Tests und Bereitstellungsvorgänge.

Voraussetzungen

Bevor Sie die GitLab CI/CD-Integration einrichten, stellen Sie sicher, dass Sie haben:

• Eine GitLab-Konto mit einem Projektrepository
• Ein Capgo-Konto mit einer konfigurierten App
• Node.js und npm/yarn in Ihrem Projekt konfiguriert

Einrichten von GitLab CI/CD

Schritt 1: Umgebungsvariablen konfigurieren

Zunächst müssen Sie in Ihrem GitLab-Projekt die notwendigen Variablen einrichten:

1. Navigieren Sie zu Ihrem GitLab-Projekt
2. Gehe zu Einstellungen → CI/CD → Variablen
3. Fügen Sie die folgenden Variablen hinzu:

Variablenname	Wert	Geschützt	Verdeckt
CAPGO_TOKEN	Ihr Capgo API Token	✅ Ja	✅ Ja

Tipps

Ermitteln Sie Ihr Capgo API Token von console.capgo.app/apikeysIhr App-ID ist bereits in Ihrem capacitor.config.ts Datei konfiguriert.

Einfach

Grundlegende Konfiguration, die auf jeden Push in die Hauptzweig in die Produktion deployt:

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

Erweitert

Feature-Zweig-Deployments

Deployen Sie Feature-Zweige in Testkanäle für die Überprüfung und Testung:

# 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

Tipps

Testen mit Kanälen: Nach der Bereitstellung in einem Feature-Kanal können Sie die Aktualisierung in Ihrer App testen, indem Sie die App so konfigurieren, dass sie diesen spezifischen Kanal verwendet. Erfahren Sie mehr über die Konfiguration von Kanälen in Ihrer App Konfigurieren Sie Kanäle in Ihrer App.

Verwendung der Verschlüsselung

Wenn Sie die Verschlüsselungsfunktion von __CAPGO_KEEP_0__ verwenden Capgo’s encryption featureNachdem Sie die Verschlüsselungsschlüssel lokal eingerichtet haben, fügen Sie Ihren privaten Schlüssel zu den GitLab-Variablen hinzu:

Terminalfenster Zur Vervollständigung in die Zwischenablage kopieren Terminalfenster

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

Fügen Sie diesen Inhalt als CAPGO_PRIVATE_KEY im Variablenbereich Ihres GitLab-Projekts (als geschützt und maskiert markieren) ein, und verwenden Sie ihn dann in Pipelines:

# 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

Achtung

Sicherheitshinweise:

• Kommt nie das .capgo_key_v2 Datei in die Versionskontrolle
• Speichern Sie den privaten Schlüssel nur in einer sicheren CI/CD-Schlüsselverwaltung
• Verwenden Sie unterschiedliche Schlüssel für unterschiedliche Umgebungen

Multi-Channel-Konfiguration

Für umfassende Informationen zur Einrichtung und Verwaltung mehrerer Bereitstellungskanäle, siehe die Channels-Dokumentation.

Vollständige Konfiguration mit mehreren Umgebungen und Merge-Request-Bereitstellungen:

# .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-Umgebung mit manuellem Genehmigung

Für Produktionsbereitstellungen, die eine manuelle Genehmigung erfordern:

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

Branch-basierte Bereitstellungsstrategie

Deploy verschiedene Branches automatisch auf die entsprechenden Kanäle:

# 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

Sicherheitsbest Practices

Schutzvariablen

1. Markiere sensible Variablen: Markiere immer API-Tokens als geschützt und maskiert
2. Zweig-Schutz: Verwenden Sie geschützte Variablen für Produktions-Deployments
3. Zugriffssteuerung: Beschränken Sie den Zugriff auf Variablen auf Maintainer nur
4. Regelmäßige Rotation: Rotieren Sie API-Tokens regelmäßig

Secure Pipeline-Konfiguration

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

Überwachung und Benachrichtigungen

Slack-Integration

Slack-Benachrichtigungen zu Ihrer Pipeline hinzufügen:

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

E-Mail-Benachrichtigungen

Konfigurieren Sie E-Mail-Benachrichtigungen in Ihren GitLab-Projekt-Einstellungen oder verwenden Sie den 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

Fehlerbehebung

Abschnitt mit dem Titel "Fehlerbehebung"

Pipeline fails with “Capgo CLI not found”:

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

Zwischenablage kopieren

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

Zwischenablage kopieren

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

Zwischenablage kopieren

Hinzufügen von Debugging-Informationen, um Probleme zu lösen:

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

Zukünftige Schritte

• Erkunden Sie Kanäle um verschiedene Bereitstellungsumgebungen zu verwalten
• Erkunden Sie Benutzerdefinierte Speicherung zur Verwaltung fortgeschrittener Bereitstellungsszenarien
• Einstellungen Verschlüsselung für sichere Bereitstellungen
• Konfigurieren Aktualisierungsverhalten um die Anwendung von Updates anzupassen

Mit der GitLab CI/CD-Integration können Sie Ihre Capgo-Bereitstellungen automatisieren und sicherstellen, dass Ihre mobilen App-Benutzer konsistente und zuverlässige Updates erhalten.

Weitermachen von GitLab CI/CD-Integration

Wenn Sie GitLab CI/CD-Integration verwenden um die CI/CD-Automatisierung zu planen, verbinden Sie es mit __CAPGO_KEEP_0__ CI/CD Capgo CI/CD zur Produktworkflow in Capgo CI/CD, Capgo Native Builds zur Produktworkflow in Capgo Native Builds, Capgo Integrations zur Produktworkflow in Capgo Integrations, CI/CD-Integration zur Implementierungsdetail in CI/CD-Integration, und GitHub Actions-Integration zur Implementierungsdetail in GitHub Actions-Integration.