CI/CD-Integration

Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.

Die Integration von Capgo in deine CI/CD-Pipeline ermöglicht es dir, den Prozess zum Bauen und Deployen von Updates für deine App vollständig zu automatisieren. Mit Capgo CLI und semantic-release sorgst du für konsistente, zuverlässige Deployments und schnelle Iterationen.

Vorteile der CI/CD-Integration

Automatisierung: Keine manuellen Schritte und kein Raum für menschliche Fehler mehr. Dein gesamter Build-, Test- und Deployment-Prozess lässt sich durchgängig automatisieren.
Konsistenz: Jedes Deployment folgt denselben Schritten und sorgt so für einen vorhersehbaren und reproduzierbaren Prozess. Das ist besonders wertvoll, wenn mehrere Teammitglieder an code mitarbeiten.
Schnellere Iterationen: Mit automatisierten Deployments kannst du Updates häufiger und mit gutem Gefühl ausrollen. Kein Warten mehr auf manuelle QA oder Release-Freigaben.

Capgo CLI

Die Capgo CLI ist der Schlüssel, um Capgo in deinen CI/CD-Workflow zu integrieren. Sie bietet Befehle zum Pushen neuer Bundle-Versionen, zum Verwalten von Channels und mehr.

Der wichtigste Command 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 sie auf eine der folgenden Arten bereitstellen:

Über einen Dateipfad zum privaten Schlüssel:

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

Direkt über den Inhalt des privaten Schlüssels (empfohlen für CI/CD):

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

Über 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"

Umgebungsvariablen für die Verschlüsselung einrichten

In CI/CD-Umgebungen empfiehlt es sich, den privaten Schlüssel als Umgebungsvariable statt als Datei zu speichern. So richtest du ihn ein:

Inhalt des privaten Schlüssels abrufen:
Terminalfenster
```
cat .capgo_key_v2 | pbcopy
```
Dies kopiert den Schlüsselinhalt in deine Zwischenablage.
Füge ihn deiner CI/CD-Umgebung hinzu:
- GitHub Aktionen: Hinzufügen CAPGO_PRIVATE_KEY zu Ihren Repository-Secrets
- GitLab CI: Füge es als maskierte Variable in deinen Projekteinstellungen hinzu
- CircleCI: Füge es als Umgebungsvariable in deinen Projekteinstellungen hinzu
- Jenkins: Füge es als Secret-Text-Credential hinzu

Nutze es in deiner 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, den Inhalt des Private Keys direkt als String zu übergeben. Das ist ideal für Umgebungsvariablen in CI/CD-Pipelines, wenn keine temporären Dateien erstellt werden sollen.

Dieser Befehl lädt den aktuellen Web-Build in den angegebenen Channel hoch. Du führst dies normalerweise als letzten Schritt in deiner CI/CD-Pipeline aus, nachdem dein Web-Build erfolgreich abgeschlossen wurde.

Capgo in deiner CI/CD-Pipeline einrichten

Die genauen Schritte hängen von deinem CI/CD-Tool ab, aber der allgemeine Prozess zur Integration von Capgo sieht in etwa so aus:

Erstelle einen API-Key: Melde dich im Capgo-Dashboard an und erstelle einen neuen API-Key. Dieser Key wird verwendet, um die CLI in deiner CI/CD-Umgebung zu authentifizieren. Halte ihn geheim und commite ihn niemals in dein Repository!
Konfiguriere bundle upload Befehl: Füge einen Schritt zu deiner CI/CD-Konfiguration 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 Ersetze Production mit dem Channel, zu dem du deployen möchtest, ${{ secrets.CAPGO_API_KEY }} mit der Umgebungsvariable, die deinen API-Key enthält, und füge hinzu --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" falls du Verschlüsselung nutzt.

Füge den upload Schritt nach deinem Web-Build hinzu: Stelle sicher, dass der upload : Stelle sicher, dass der Schritt erst nach dem erfolgreichen Abschluss deines Web-Builds kommt. So deployest du immer dein neuestes code. Hier ist eine Beispielkonfiguration für GitHub Actions:

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

Versionsmanagement mit Semantic-release

Der empfohlene Weg für das Versioning mit Capgo ist es, die Version in deiner capacitor.config.ts Datei festzulegen, indem du sie daraus importierst package.json:

import pkg from './package.json'

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

Mit diesem Ansatz kannst du:

semantic-release (oder ein anderes Tool) nutzen, um die package.json Version
deine App automatisch mit der aktualisierten Version bauen,
das Bundle mit der korrekten Version hochladen.

Dein CI/CD-Workflow sieht so aus:

- run: npm ci
- run: npx semantic-release  # Updates package.json version
- run: npm run build         # Builds with new version from capacitor.config
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

Hier ist ein Beispiel für eine .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 bewirkt Folgendes:

Analysiert Commit-Messages gemäß der Conventional Commits Spec, um die nächste Versionsnummer zu bestimmen.
Erstellt 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 deiner capacitor.config übernommen wird.
Commitet die aktualisierte CHANGELOG.md, package.json, sowie alle weiteren geänderten Dateien zurück in das Repository.

Stelle sicher, dass du semantic-release vor dem App-Build ausführst, damit die aktualisierte Version von package.json über die capacitor.config in deinen Build einfließt.

Auto-Bump, wenn die lokale Version bereits auf Capgo ist

Bundle-Namen müssen eindeutig sein (gelöschte Versionen belegen den Namen weiterhin). Wenn die CI dieselbe package.json Version hochlädt, schlägt der Upload fehl. Erhöhe lieber die package.json Version (z. B. mit semantic-release). Ist das nicht praktikabel, lässt CLI die nächste freie Semver-Version aus dem verknüpften Bundle des Channels wählen, andernfalls die neueste Remote-App-Version:

npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @capgo/cli@latest bundle upload --channel=production --auto-bump ai

--auto-bump ai nutzt Capgo Cloudflare Workers AI, um lokale Bundle-Dateien mit den vorherigen Capgo/Channel-Delta-Dateien zu vergleichen, wählt aus major | minor | patch | metadataund gibt einen kurzen Grund aus. Ohne vorherige Capgo-Version wird die KI übersprungen und der Bump ist ein Patch.

Nicht kombinieren --auto-bump mit --bundle / -b. Siehe die bundle upload Referenz für die vollständige Optionsliste.

Fehlerbehebung

Falls Probleme bei deiner Capgo CI/CD-Integration auftreten, prüfe bitte Folgendes:

API Key: Stelle sicher, dass dein API Key gültig ist und die nötigen Berechtigungen hat. Falls du eine Umgebungsvariable nutzt, prüfe, ob diese korrekt gesetzt ist.
CLI-Version: Stelle sicher, dass du die neueste Version von Capgo CLI verwendest. Ältere Versionen können Kompatibilitätsprobleme haben oder bestimmte Funktionen fehlen.
Build-Artefakte: Prüfe, ob dein Web-Build die erwarteten Output-Dateien erzeugt. Der Capgo CLI braucht einen gültigen Web-Build, um ein Bundle zu erstellen.
Netzwerkverbindung: Stelle sicher, dass deine CI/CD-Umgebung Netzwerkzugriff auf die Capgo Server hat. Firewall- oder Proxy-Probleme können dies manchmal beeinträchtigen. upload Befehl.

Falls du weiterhin Probleme hast, wende dich an den Capgo Support. Das Team hilft dir gerne bei der Fehlersuche in deinem spezifischen Setup.

Fazit

Die Integration von Capgo in deine CI/CD-Pipeline mit sauberem Version-Management kann deinen Entwicklungs-Workflow deutlich vereinfachen. Durch die Automatisierung von Deployments und Versionierung via capacitor.config kannst du Updates schneller und mit mehr Sicherheit ausrollen.

Der empfohlene Weg, die Version in deiner capacitor.config.ts Datei und semantic-release zum Aktualisieren verwenden package.json ermöglicht einen robusten und zuverlässigen Deployment-Prozess. So kannst du dich auf das Bauen guter Features konzentrieren, statt dich um manuelle Release-Schritte zu kümmern.

Weitere Details zu den Capgo CLI Commands und Optionen findest du in der CLI Referenz. Und für einen tieferen Einblick in die semantic-release-Konfiguration schau in die semantic-release-Docs.

Viel Erfolg beim Deployment!

Weiter geht's mit der CI/CD-Integration

Wenn du es nutzt CI/CD-Integration um CI/CD-Automatisierung zu planen, verbinde es mit Capgo CI/CD für den Produkt-Workflow in Capgo CI/CD, Capgo Native Builds optimieren für den Produkt-Workflow in Capgo Native Builds, Capgo Integrationen für den Produkt-Workflow in Capgo Integrations, GitHub Actions-Integration für die Implementierungsdetails in der GitHub Actions Integration und GitLab CI/CD-Integration für die Implementierungsdetails in der GitLab CI/CD Integration.