CI/CD-Integration

Die Integration von Capgo in Ihre CI/CD-Pipeline ermöglicht es Ihnen, den Prozess des Erstellens und Bereitstellens von Updates für Ihre App vollständig zu automatisieren. Durch die Nutzung der Capgo CLI und semantic-release können Sie konsistente, zuverlässige Bereitstellungen sicherstellen und schnelle Iterationen ermöglichen.

Vorteile der CI/CD-Integration

Automatisierung: Keine manuellen Schritte mehr oder Raum für menschliche Fehler. Ihr gesamter Build-, Test- und Bereitstellungsprozess kann von Anfang bis Ende automatisiert werden.
Konsistenz: Jede Bereitstellung folgt den gleichen Schritten und gewährleistet einen vorhersehbaren und wiederholbaren Prozess. Dies ist besonders wertvoll, wenn mehrere Teammitglieder Code beisteuern.
Schnellere Iterationen: Mit automatisierten Bereitstellungen können Sie Updates häufiger und mit Zuversicht ausliefern. Kein Warten mehr auf manuelle QA oder Freigabegenehmigungen.

Capgo CLI

Die Capgo CLI ist der Schlüssel zur Integration von Capgo in Ihren CI/CD-Workflow. Sie bietet Befehle zum Pushen neuer Bundle-Versionen, Verwalten von Kanälen und mehr.

Der wichtigste Befehl für die CI/CD-Integration ist bundle upload:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY

Wenn Sie Verschlüsselung verwenden, sollten Sie diese auf eine der folgenden Arten bereitstellen:

Verwendung eines privaten Schlüsseldateipfads:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATH

Direktes Verwenden des privaten Schlüsselinhalts (empfohlen für CI/CD):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENT

Verwendung von Umgebungsvariablen (Best Practice für CI/CD):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"

Einrichten von Umgebungsvariablen für Verschlüsselung

Für CI/CD-Umgebungen wird empfohlen, Ihren privaten Schlüssel als Umgebungsvariable statt als Datei zu speichern. So richten Sie es ein:

Holen Sie sich den Inhalt Ihres privaten Schlüssels:
Terminal-Fenster
```
cat .capgo_key_v2 | pbcopy
```
Dies kopiert den Schlüsselinhalt in Ihre Zwischenablage.
Fügen Sie ihn zu Ihrer CI/CD-Umgebung hinzu:
- GitHub Actions: Fügen Sie CAPGO_PRIVATE_KEY zu Ihren Repository-Secrets hinzu
- GitLab CI: Fügen Sie ihn als maskierte Variable in Ihren Projekteinstellungen hinzu
- CircleCI: Fügen Sie ihn als Umgebungsvariable in Ihren Projekteinstellungen hinzu
- Jenkins: Fügen Sie ihn als Secret-Text-Credential hinzu

Verwenden Sie ihn in Ihrer Pipeline:

- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Hinweis: Das --key-data-v2 Flag ermöglicht es Ihnen, den Inhalt des privaten Schlüssels direkt als String zu übergeben, was perfekt für Umgebungsvariablen in CI/CD-Pipelines ist, wo Sie keine temporären Dateien erstellen möchten.

Dieser Befehl lädt den aktuellen Web-Build in den angegebenen Kanal hoch. Sie führen dies typischerweise als letzten Schritt in Ihrer CI/CD-Pipeline aus, nachdem Ihr Web-Build erfolgreich abgeschlossen wurde.

Einrichtung von Capgo in Ihrer CI/CD-Pipeline

Während die genauen Schritte je nach gewähltem CI/CD-Tool variieren, sieht der allgemeine Prozess zur Integration von Capgo wie folgt aus:

API-Schlüssel generieren: Melden Sie sich beim Capgo-Dashboard an und erstellen Sie einen neuen API-Schlüssel. Dieser Schlüssel wird zur Authentifizierung der CLI in Ihrer CI/CD-Umgebung verwendet. Halten Sie ihn geheim und committen Sie ihn niemals in Ihr Repository!
Konfigurieren Sie den bundle upload Befehl: Fügen Sie Ihrer CI/CD-Konfiguration einen Schritt hinzu, der den bundle upload Befehl mit den entsprechenden Argumenten ausführt:
upload.yml
```
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}
```
\n Ersetzen Sie Production mit dem Kanal, in den Sie deployen möchten, ${{ secrets.CAPGO_API_KEY }} mit der Umgebungsvariable, die Ihren API-Schlüssel enthält, und fügen Sie --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" hinzu, wenn Sie Verschlüsselung verwenden.

Fügen Sie den upload Schritt nach Ihrem Web-Build hinzu: Stellen Sie sicher, dass der upload Schritt nach erfolgreichem Abschluss Ihres Web-Builds erfolgt. Dies stellt sicher, dass Sie immer Ihren neuesten Code bereitstellen.\n Hier ist ein Beispiel für die Konfiguration für GitHub Actions:\n

name: Deploy to Capgo
 on:
  push:
   branches: [main]

jobs:
 deploy:
 runs-on: ubuntu-latest

 steps:
 - uses: actions/checkout@v6
 - uses: actions/setup-node@v6
  with:
   node-version: '24'

 - run: npm ci
 - run: npm run build

 - run: npm install -g @capgo/cli
 - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Versionsverwaltung mit Semantic-release

Der empfohlene Weg zur Handhabung der Versionierung mit Capgo ist, die Version in Ihrer capacitor.config.ts Datei durch Import aus package.json zu setzen:

import pkg from './package.json'

const config: CapacitorConfig = {
  // ... andere Konfigurationen
  plugins: {
    CapacitorUpdater: {
      version: pkg.version,
    }
  }
}

Dieser Ansatz ermöglicht es Ihnen:

Semantic-release (oder ein anderes Tool) zu verwenden, um die package.json Version zu aktualisieren
Ihre App mit der automatisch enthaltenen aktualisierten Version zu bauen
Das Bundle mit der korrekten Version hochzuladen

Ihr CI/CD-Workflow würde so aussehen:

- run: npm ci
- run: npx semantic-release  # Aktualisiert package.json Version
- run: npm run build         # Baut mit neuer Version aus capacitor.config
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

Hier ist eine Beispiel-.releaserc Konfigurationsdatei für semantic-release:

{
  "branches": [
    "main",
    {
      "name": "beta",
      "prerelease": true
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

Diese Konfiguration führt Folgendes aus:

Analysiert Commit-Nachrichten, um die nächste Versionsnummer nach der Conventional Commits-Spezifikation zu bestimmen.
Generiert Release Notes basierend auf den Commits seit dem letzten Release.
Aktualisiert die CHANGELOG.md Datei mit den neuen Release Notes.
Aktualisiert die package.json Version, die von Ihrer capacitor.config übernommen wird.
Committet die aktualisierte CHANGELOG.md, package.json und alle anderen geänderten Dateien zurück ins Repository.

Stellen Sie sicher, dass Sie semantic-release vor dem Build Ihrer App ausführen, damit die aktualisierte Version aus package.json durch die capacitor.config in Ihren Build aufgenommen wird.

Fehlerbehebung

Wenn Sie Probleme mit Ihrer Capgo CI/CD-Integration haben, hier einige Dinge, die Sie überprüfen sollten:

API-Schlüssel: Stellen Sie sicher, dass Ihr API-Schlüssel gültig ist und die erforderlichen Berechtigungen hat. Wenn Sie eine Umgebungsvariable verwenden, überprüfen Sie, ob sie korrekt gesetzt ist.
CLI-Version: Stellen Sie sicher, dass Sie die neueste Version der Capgo CLI verwenden. Ältere Versionen können Kompatibilitätsprobleme haben oder bestimmte Funktionen fehlen.
Build-Artefakte: Bestätigen Sie, dass Ihr Web-Build die erwarteten Ausgabedateien generiert. Die Capgo CLI benötigt einen gültigen Web-Build, um ein Bundle zu erstellen.
Netzwerkverbindung: Überprüfen Sie, ob Ihre CI/CD-Umgebung Netzwerkzugriff auf die Capgo-Server hat. Firewall- oder Proxy-Probleme können manchmal den upload Befehl stören.

Wenn Sie immer noch Probleme haben, wenden Sie sich an den Capgo-Support. Sie können bei der Fehlerbehebung für Ihre spezifische Einrichtung helfen.

Fazit

Die Integration von Capgo in Ihre CI/CD-Pipeline mit ordnungsgemäßer Versionsverwaltung kann Ihren Entwicklungsworkflow erheblich vereinfachen. Durch die Automatisierung Ihrer Bereitstellungen und Versionierung durch den capacitor.config-Ansatz können Sie Updates schneller und mit mehr Zuversicht ausliefern.

Der empfohlene Ansatz, die Version in Ihrer capacitor.config.ts Datei zu setzen und semantic-release zur Aktualisierung von package.json zu verwenden, bietet einen robusten und zuverlässigen Bereitstellungsprozess, der es Ihnen ermöglicht, sich auf das Entwickeln großartiger Funktionen zu konzentrieren, anstatt sich über manuelle Release-Schritte Gedanken zu machen.

Weitere Details zu den Capgo CLI-Befehlen und Optionen finden Sie in der CLI-Referenz. Und für einen tieferen Einblick in die semantic-release-Konfiguration, siehe die semantic-release Dokumentation.

Viel Spaß beim Bereitstellen!