GitHub Aktionen

Einen Einrichtungsvorschlag mit den Installationsanweisungen und der vollständigen Markdown-Guideline für diesen Plugin kopieren.

Automatisieren Sie Ihre iOS- und Android-Builds direkt aus Ihrem GitHub-Repository. Mit einem Workflow-File und einigen Repository-Secrets kann jede Push, Tag oder manuelle Auslösung signierte, in den Laden lieferfähige Apps erzeugen — ohne dass jemand auf der Team ein Mac, Xcode oder Android Studio installiert hat.

Was Sie erhalten

Risikofreie Releases

Tagen Sie eine Release in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store übermittelt.

Keine lokale Einrichtung

Mitglieder von Windows- oder Linux-Teams können iOS-Builds auslösen. Kein Xcode, keine Bereitstellungsschwierigkeiten, keine gemeinsam genutzten Signierungszertifikate, die auf Laptops herumfliegen.

Gescoppte Geheimnisse

Kredenziale leben in GitHub-Repository-Secrets, die auf Ihr Repository und nur für den Workflow-Runner sichtbar sind. Leicht zu rotieren, leicht zu überprüfen.

Parallele Builds

Erstellen Sie iOS- und Android-Apps gleichzeitig mit einem Matrix-Auftrag. Ein typischer Release dauert weniger als 10 Minuten.

Voraussetzungen

Bevor Sie die Workflow-Einrichtung vornehmen, stellen Sie sicher, dass Sie haben:

Ein Capgo-Konto mit einer aktiven Abonnement und einem Capgo API-Schlüssel
Ihre App in Capgo (bunx @capgo/cli@latest app add wenn nicht
Build-Zertifikate konfiguriert lokal mit bunx @capgo/cli@latest build init — siehe Managing Credentials für die Anleitung zum Wizard
Einen erfolgreichen lokalen Build (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug — CI ist nicht der Ort, um Ihr erstes Build zu debuggen
Das GitHub CLI (gh) installiert und angemeldet (gh auth login)

Einstellung

Das Capgo CLI kann Ihre lokalen Anmeldeinformationen als fertig vorbereitete .env Datei exportieren. Kombiniert mit gh secret set -fDies wendet die gesamte CI/CD-Konfiguration auf drei Befehle um — keine manuelle Base64-Codierung, keine JSON-Verwaltung, keine Kopieren und Einfügen von Geheimnissen.

Fügen Sie Ihren Capgo API-Schlüssel als Repository-Geheimnis hinzu

Der API-Schlüssel gehört nicht zum per-Anwendungskonto-geheimen Speicher, fügen Sie ihn daher einmal manuell hinzu:
Terminal-Fenster
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Erstellen Sie den Schlüssel im Capgo-Dashboard mit Upload-Berechtigungen oder höher. Exportieren Sie Ihre Anmeldeinformationen in eine
Datei .env with

Führen Sie den interaktiven Credentials-Manager aus:
Terminalfenster
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Wählen Sie in der TUI Als .env-Datei exportierenDie CLI schreibt .env.capgo.<appId> in Ihr aktuellen Verzeichnis mit Modus 0600 (nur für den Besitzer lesbar) — zum Beispiel .env.capgo.com.example.appWenn sowohl iOS als auch Android konfiguriert sind, landen die Geheimnisse beider Plattformen in derselben Datei unter # === IOS === und # === ANDROID === Überschriften. iOS- und Android-Umgebungsvariablen-Namen sind getrennt, daher ist ihre Combination konfliktfrei.

Pass --platform ios (oder --platform android) um den Manager auf eine Plattform zu beschränken. Die Ausgabe produziert dann eine Datei pro Plattform wie .env.capgo.com.example.app.iosNützlich, wenn iOS- und Android-Secrets in verschiedenen Repositories oder Umgebungen leben.

Ein paar Konfigurations-Schalter (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) können unter jeder Plattform unabhängig voneinander gespeichert werden und mögen sich auseinanderentwickelt haben. Wenn der Manager eine Auseinandersetzung findet, druckt er die konfligierenden Schlüssel aus, fragt nach expliziter Bestätigung vor der Schreibvorgang und fügt die Konfliktliste als Kommentar an der oberen Seite der Datei ein. Re-export mit --platform Wenn Sie per-Plattform-Werte beibehalten möchten.
Schieben Sie die .env Datei zu GitHub Actions-Secrets

Die gh secret set -f Befehl liest eine dotenv-Datei und erstellt eine Repository-Schlüssel pro Zeile: KEY=value Terminalfenster
In die Zwischenablage kopieren
```
gh secret set -f .env.capgo.com.example.app
```
That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.
Sie enthält plaintext-Signiermaterial. Sobald Sie es in __CAPGO_KEEP_0__ gepusht haben:
It contains plaintext signing material. Once you’ve pushed it to GitHub:
In die Zwischenablage kopieren
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Terminalfenster
Erstelle das Workflow-File

Hinzufügen .github/workflows/capgo-build.yml zu deinem Repository. Wähle eines der drei Triggermuster unten aus, je nachdem, wie du Builds auslösen möchtest.

Was landet in deinen Geheimnissen

Zum Verweis: gh secret set -f wird diese Repository-Secrets erstellen (Dein Workflow-YAML verweist auf sie mit diesen genauen Namen):

Plattform	Erstellte Geheimnisse
iOS	`BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `CAPGO_IOS_PROVISIONING_MAP_BASE64`, `APPLE_KEY_ID`, `APPLE_ISSUER_ID`, `APPLE_KEY_CONTENT`, `APP_STORE_CONNECT_TEAM_ID`
Android	`ANDROID_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
(hinzugefügt manuell)	`CAPGO_TOKEN`

You brauchen diese nicht zu memorieren — die Workflow-Beispiele unten verweisen bereits auf alle von ihnen.

Workflow-Beispiele

Die drei Beispiele unten umfassen die gängigsten Muster. Sie verwenden alle die gleiche Form: Überprüfen Sie das Repository, installieren Sie die Abhängigkeiten, erstellen Sie die Web-Assets, synchronisieren Sie sie mit der nativen Plattform und rufen Sie dann Capgo Build mit übergebenen Umgebungsvariablen auf.

1. Manueller Trigger

Erstellt einen Build, der von jedem mit Schreibzugriff ausgelöst werden kann, aus der Aktionen Registerkarte in GitHub mit einer Plattform-Abwähle. Nützlich für ad-hoc-Testbuilds oder die Auslösung einer Veröffentlichung auf Anforderung.

name: Capgo Build (Manual)

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Platform to build'
        required: true
        default: 'android'
        type: choice
        options: [ios, android, both]
      mode:
        description: 'Build mode'
        required: true
        default: 'debug'
        type: choice
        options: [debug, release]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync

      - name: Trigger Capgo Build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ inputs.platform }} \
            --build-mode ${{ inputs.mode }}

Ersetzen com.example.app mit Ihrer App-ID. Sobald Sie es verpflichtet haben, gehen Sie zu Aktionen → Capgo Build (Manuell) → Workflow ausführen um es auszulösen.

2. Release auf Tag

Baut und versendet beide Plattformen parallel, sobald Sie eine Versionsmarke wie v1.4.0dies ist die am häufigsten verwendete Produktionskonfiguration — git tag v1.4.0 && git push --tags wird zu Ihrem Release-Befehl.

name: Capgo Build (Release)

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}

      - name: Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # iOS
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          # Android
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

Die Matrix läuft iOS und Android parallel auf separaten Ausführern ab. Wenn Sie fail-fast: false bedeuten, dass ein fehlgeschlagener iOS-Build den in Arbeit befindlichen Android-Build nicht abbrechen wird (und umgekehrt) — nützlich, wenn eine Plattform ein vorübergehendes Signierungsproblem hat.

3. Debug-Build bei Push auf Haupt

Fängt native Build-Regressionen frühzeitig ab, indem es bei jedem Push auf ein Debug-Android-Build produziert. mainGünstig, schnelle Feedback und Sie können die Play Store-Uploads auslassen, um es rein als Rauchtest zu halten.

name: Capgo Build (Main)

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'android/**'
      - 'ios/**'
      - 'package.json'
      - 'capacitor.config.*'

jobs:
  smoke-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync android

      - name: Smoke build (Android debug)
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform android \
            --build-mode debug \
            --no-playstore-upload \
            --output-upload

Sichert die Durchführung des Workflows, wenn nur Dokumentation geändert wurde. paths Überspringt die Einreichung bei der Google Play Store (nicht erforderlich) und --no-playstore-upload erzeugt eine Download-URL für das resultierende APK, damit Sie es auf einem Testgerät installieren können. PLAY_CONFIG_JSON Gemeinsame Muster --output-upload Abschnitt mit dem Titel “Gemeinsame Muster”

Überspringen Sie die Einreichung bei der Google Play Store / TestFlight

Für Testversionen überspringen Sie die Einreichung bei der App Store: Android verwendet

(was nie in die App Store eingereicht wird). Combine entweder mit --no-playstore-upload__CAPGO_KEEP_0__ --ios-distribution ad_hoc __CAPGO_KEEP_1__ --output-upload um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten.

Die Ausgabeadresse der Build-URL und QR code lesen.

Pass --output-record <path> um die Build-Artikel-URL und QR code auf der Festplatte zu speichern, wenn die Build erfolgreich ist, und sie in nachfolgenden Schritten wieder zu lesen. build last-outputKeine Log-Scraping, keine Regex.

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform android --build-mode debug \
      --output-upload --output-retention 1d \
      --output-record /tmp/build.json

- name: Comment on PR with build URL
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl)
    if [ -n "$URL" ]; then
      gh pr comment ${{ github.event.pull_request.number }} \
        --body "Debug build ready: $URL"
    fi

--output-record /tmp/build.json eine JSON-Datei (mit jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) und eine PNG-QR code nebenbei schreibt. /tmp/build.json.qr.png. build last-output sie wieder einliest:

--field outputUrl nur die Download-URL (Zeilenende; sicher für URL=$(...)).
--field qrCodePngPath die PNG-Pfad druckt, damit Sie es als PR-Anhänge hochladen können.
--qr druckt die renderete ASCII-QR — fügen Sie es in einen Markdown code-Fence in der PR-Kommentar für eine inline-Scannbarkeit ein.

Überspringen Sie die Build-Nummer-Erhöhung

Standardmäßig erhöht jede Release-Build die Build-Nummer. Um sie auf einen Wert zu fixieren, den Sie kontrollieren (z. B. den Git-Tag), geben Sie --skip-build-number-bump:

- name: Set version from tag
  run: |
    VERSION="${GITHUB_REF#refs/tags/v}"
    # Update package.json or your version source here
    bun pm version "$VERSION" --no-git-tag-version

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform ios --build-mode release \
      --skip-build-number-bump

Cache Abhängigkeiten

bun install ist bereits schnell genug, dass ein JS-Abhängigkeits-Cache nur selten einen Gewinn bringt, aber Capacitor’s native Abhängigkeiten (CocoaPods, Gradle) lohnen sich für größere Projekte:

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

Fehlersuche

Symptom	Wahrscheinliche Ursache
`CAPGO_TOKEN is not set`	Geheimes nicht hinzugefügt oder Job hat keinen Zugriff darauf (Überprüfe Umgebungs-/Zweig-Schutzmaßnahmen)
Fehlende iOS / Android-Zugangsdatenfehler	`gh secret set -f` wurde nicht ausgeführt oder wurde gegen ein anderes Repository ausgeführt. Überprüfe mit `gh secret list`
`cap sync` Funktioniert nicht in CI, aber lokal funktioniert	Ein natives Plugin ist nicht in `package.json` oder du hast es vergessen `bun install` vorher `cap sync`
Der Build ist erfolgreich, aber die App erscheint nicht in App Store Connect	Falsche Team-ID oder das App-Record existiert noch nicht in App Store Connect. Überprüfen Sie lokal mit `bunx @capgo/cli@latest build credentials manage`
Der Build hängt nach „Uploading project“	Das Projektarchiv ist ungewöhnlich groß — überprüfen Sie, ob `node_modules` nicht hochgeladen wird (das sollte nicht der Standardfall sein)
`Provisioning profile doesn't match bundle ID`	Der Provisioning-Map verweist auf eine andere Bundle-ID als die, die Xcode signiert. Rufen Sie `build init` den Profil-Refresh neu auf, dann exportieren Sie erneut mit `build credentials manage`
Die lokalen Anmeldeinformationen wurden geändert, aber CI schlägt noch immer fehl	Vergessen Sie nicht, erneut zu exportieren und erneut zu pushen: `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Der Manager weigert sich, das kombinierte Datei zu schreiben	Die Shared-Config-Schlüssel unterscheiden sich zwischen Plattformen — der Manager warnt und fragt nach Bestätigung. Bestätigen Sie entweder, um einen von beiden zu überschreiben, oder exportieren Sie pro Plattform erneut `--platform ios` / `--platform android`
`build last-output` druckt eine leere URL	Die Build war nicht erfolgreich `--output-upload`, oder sie scheiterte, bevor ein Artefakt erstellt wurde. `outputUrl` wird sein `null` im Protokoll. Auf `[ -n "$URL" ]` vor der Verwendung
`build last-output` Fehler mit `Unsupported record schemaVersion`	Der Runner ist auf einem älteren CLI als dem, der das Protokoll geschrieben hat. Pin beide Produzent und Leser auf die gleiche explizite Version (z.B. `bunx @capgo/cli@7.104.0 …` auf beiden Seiten) anstatt `@latest`, die schwimmt und zwischen den Aufträgen treiben kann

Für plattform-spezifische Build-Fehler siehe die Troubleshooting-Anleitung.

Weitere Schritte

Anmeldeinformationen einrichten Vollständige Referenz für die Vorbereitung von iOS- und Android-Zertifikaten als Base64-Secrets.

iOS-Builds Tieferer Leitfaden zu Zertifikaten, Profilen und der App-Store-Abgabe.

Android-Builds Keystore-Einrichtung, Play-Store-Dienstkonten und Flavor-Verwaltung.

Konfigurationsoptionen Alle CLI-Flags und Umgebungsvariablen für die Feinjustierung Ihrer Builds.