GitHub Aktionen

Ein Setup-Prompt mit den Installations-Schritten und der vollständigen Markdown-Guideline für diesen Plugin kopieren.

Automatisieren Sie Ihre iOS- und Android-Builds direkt aus Ihrem GitHub-Repository. Mit einer Workflow-Datei und einigen Repository-Secrets können Sie mit jedem Push, Tag oder manuellen Trigger 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

Hands-free Releases

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

Keine lokale Einrichtung

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

Gesicherte Geheimnisse

Benutzerkennungen leben in GitHub Repository-Secrets, die auf Ihr Repository beschränkt sind und nur dem Workflow-Runner sichtbar sind. Sie sind leicht zu rotieren und leicht zu überprüfen.

Parallel Builds

Mit einem Matrix-Auftrag iOS- und Android-Apps gleichzeitig bauen. Ein typischer Release dauert weniger als 10 Minuten.

Voraussetzungen

Ein __CAPGO_KEEP_0__-Konto mit einer aktiven Abonnement und einem

Capgo __CAPGO_KEEP_1__-Schlüssel Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add Die Build-Kennungen sind lokal konfiguriert mit
— siehe bunx @capgo/cli@latest build init — see Kontomanagement für die Zaubererführung
Erfolgreicher lokaler Build (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI ist nicht der Ort, um Ihren ersten Build zu debuggen
Die GitHub CLI (gh) installiert und authentifiziert (gh auth login)

Einrichtung

Der Capgo CLI kann Ihre lokalen Anmeldeinformationen als fertig vorbereitete Datei exportieren. Kombiniert mit .env wird die gesamte CI/CD-Einrichtung in drei Befehle umgewandelt – keine manuelle Base64-Codierung, keine JSON-Verwaltung, keine Kopieren und Einfügen von Geheimnissen. gh secret set -fFügen Sie Ihren __CAPGO_KEEP_0__ __CAPGO_KEEP_1__-Schlüssel als Repository-Secret hinzu

Add your Capgo API key as a repository secret

The API key isn’t part of the per-app credential store, so add it once manually:
Auf die Zwischenablage kopieren
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
__CAPGO_KEEP_0__-Dashboard Capgo dashboard Hochladen Die __CAPGO_KEEP_0__-Anleitung kann exportieren Ihre lokale Anmeldeinformationen als fertig vorbereitete Datei. Rechte oder höher.
Exportieren Sie Ihre Anmeldeinformationen in ein .env Datei

Führen Sie den interaktiven Anmeldeinformationen-Manager aus:
Terminalfenster
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
In der TUI wählen Sie Auf .env exportieren. Die CLI schreibt .env.capgo.<appId> mit Modus 0600 (Eigentümerlesbar) — zum Beispiel, .env.capgo.com.example.app. Wenn sowohl iOS als auch Android konfiguriert sind, landen die Geheimnisse beider Plattformen in derselben Datei unter # === IOS === und # === ANDROID === Sektionenüberschriften. iOS- und Android-Umgebungsvariablen sind getrennt, daher ist ihre Combination konfliktfrei.

Übergeben --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.iosZweckmäßig, wenn iOS- und Android-Secrets in verschiedenen Repositories oder Umgebungen leben.

Eine Handvoll Konfigurationstaster (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 dem Schreiben und fügt die Konfliktliste als Kommentar an der Spitze der Datei ein. Re-export mit --platform If Sie Werte, die pro Plattform gespeichert werden müssen.
Pushen Sie das " .env Datei zu GitHub Actions-Secrets

Das gh secret set -f Kommando liest eine dotenv-Datei und erstellt eine Repository-Secret pro Zeile: KEY=value Fenster des Terminalfensters
Zur 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 zu __CAPGO_KEEP_0__ gepusht haben:
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Terminalfenster
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
__CAPGO_KEEP_0__
Arbeitsablaufdatei erstellen

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

Zu Referenzzwecken gh secret set -f wird folgende Repository-Schlüssel erstellt (dein Arbeitsablauf-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`

Sie müssen diese nicht auswendig lernen – die folgenden Workflow-Beispiele verweisen bereits auf alle von ihnen.

Workflow-Beispiele

Die drei folgenden Beispiele umfassen die gängigsten Muster. Sie verwenden alle dieselbe Form: Überprüfen Sie das Repository, installieren Sie die Abhängigkeiten, erstellen Sie die Web-Ressourcen, synchronisieren Sie sie mit der nativen Plattform, rufen Sie dann Capgo Build mit über Umgebungsvariablen übergebener Zugriff aus.

1. Manueller Trigger

Permits anyone with write access to start a build from the Aktionen Registerkarte in GitHub mit einer Plattform-Auswahl. 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 dies committieren, 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 Versions-Tag 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. Die Einstellung fail-fast: false bedeutet, 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 auf Push zu Main

Stellt native Build-Regressionen frühzeitig durch die Erstellung eines Debug-Builds für Android bei jedem Push zu Main fest. main. Günstig zu betreiben, 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

Die paths Der Filter stellt sicher, dass der Workflow bei nur Dokumentationsänderungen nicht ausgeführt wird. --no-playstore-upload vermeidet die Play Store-Submission (keine PLAY_CONFIG_JSON erforderlich), und --output-upload erzeugt eine Download-URL für das resultierende APK, damit Sie es auf einem Testgerät installieren können.

Gemeinsame Muster

Play Store / TestFlight-Upload auslassen

Für Testbuilds wird die Veröffentlichung im Store unterdrückt: Android verwendet --no-playstore-uploadfür iOS wird in ad-hoc-Modus mit --ios-distribution ad_hoc (was nie in den App Store einreicht). Combine entweder mit --output-upload um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten.

Bereitstellung der Veröffentlichung für die Überprüfung

Standardmäßig laden Releasebuilds das signierte Artefakt hoch und lassen die endgültige Store-Aktion unter Ihrer Kontrolle. Für CI-Veröffentlichungen, die direkt in den Store-Überprüfungsfluss einfließen sollen, fügen Sie --submit-to-store-review.

Android verwendet Ihr PLAY_CONFIG_JSON Dienstkonto und stellt die Google Play-Veröffentlichung anstelle der Inaktivität ein. Fügen Sie --store-release-name, --store-release-notes, und optional --store-release-notes-locale Einträge hinzu, wenn Sie möchten, dass die Play-Veröffentlichung den gleichen Tag und lokalisierten Versionshinweisen wie CI trägt:

- name: Submit Android release for review
  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 }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

iOS verwendet die App Store Connect API-Schlüsselverbindung und sendet die verarbeitete TestFlight-Version zur App Store-Bewertung. Es erfordert app_store Verteilung; --ios-testflight-groups ist optional für externe Beta-Verteilung und wird nicht für die App Store-Bewertung benötigt:

- name: Submit iOS build to App Store review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
    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 }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform ios \
      --build-mode release \
      --ios-distribution app_store \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \
      --no-ios-automatic-release

Lesen Sie die Ausgabeadresse der Build-URL und QR code

Gelungen --output-record <path> um die Build-Artikel-URL und QR code auf der Festplatte zu speichern, wenn die Build erfolgreich ist, und sie dann in nachfolgenden Schritten mit build last-outputKeine Log-Abfrage, 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-Datenbank (mit jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) und ein PNG-QR-code-Code nebenbei /tmp/build.json.qr.png. build last-output liest es wieder ein:

--field outputUrl druckt nur die Download-URL (neuer Zeile; sicher für URL=$(...)).
--field qrCodePngPath druckt den PNG-Pfad, damit du ihn als PR-Anhänge hochladen kannst.
--qr druckt den renderierten ASCII-QR-Code — füge ihn in einen Markdown-code-Fence in die PR-Kommentare für Inline-Scannbarkeit ein.

Skip Buildnummer erhöhen

Standardmäßig erhöht sich bei jeder Releaseversion die Buildnummer. Um sie auf einen Wert zu fixieren, den Sie kontrollieren (z.B. den Git-Tag), übergeben 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

Abhängigkeiten im Cache speichern

bun install ist bereits so schnell, dass ein JS-Abhängigkeiten-Cache nur in seltenen Fällen einen Gewinn bringt, aber Capacitor's native Abhängigkeiten (CocoaPods, Gradle) sind für größere Projekte wertvoll:

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

Problembehandlung

Symptom	Wahrscheinliche Ursache
`CAPGO_TOKEN is not set`	Kein Geheimnis wurde hinzugefügt oder der Job hat keinen Zugriff darauf (Überprüfe Umgebungs-/Branchschutz)
iOS- bzw. Android-Zugangsfehler fehlen	`gh secret set -f` nicht ausgeführt wurde oder wurde gegen eine andere Repository ausgeführt. Überprüfe mit `gh secret list`
`cap sync` fehlt in CI, aber funktioniert lokal	Ein nativer Plugin ist nicht in `package.json`oder du hast vergessen `bun install` vorher `cap sync`
Die Veröffentlichung gelingt, aber keine App erscheint in App Store Connect	Falsche Team-ID oder das App-Record existiert noch nicht in App Store Connect. Überprüfe lokal mit `bunx @capgo/cli@latest build credentials manage`
Die Veröffentlichung hängt nach „Projekt hochladen“	Das Projektarchiv ist ungewöhnlich groß — überprüfe, dass `node_modules` nicht hochgeladen wird (es sollte nicht standardmäßig hochgeladen werden)
`Provisioning profile doesn't match bundle ID`	Die Bereitstellungsmap zeigt auf einen anderen Bundle-Id als der, den Xcode signiert. Wiederholen Sie den `build init` um das Profil neu zu laden, dann neu exportieren Sie mit `build credentials manage`
Die lokalen Anmeldeinformationen wurden geändert, aber CI schlägt noch immer fehl	Denken Sie daran, neu zu exportieren und neu 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 gemeinsamen Konfigurations-Schlüssel unterscheiden sich zwischen Plattformen – der Manager warnt und fragt nach Bestätigung. Bestätigen Sie, um einschreiben zu gewinnen, oder exportieren Sie pro Plattform neu mit `--platform ios` / `--platform android`
`build last-output` druckt eine leere URL	Die Verarbeitung schlug fehl `--output-upload`, oder es schlug vor der Erstellung eines Artefakts fehl. `outputUrl` wird `null` in der Aufzeichnung. Branchen Sie sich auf `[ -n "$URL" ]` vor der Verwendung
`build last-output` Fehler mit `Unsupported record schemaVersion`	Der Runner läuft auf einem älteren CLI als dem, der das Protokoll geschrieben hat. Pin beide Produzent und Leser an 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 plattformspezifische Build-Fehler siehe die Troubleshooting-Anleitung.

Nächste Schritte

Auto OTA oder Native Branch CI zwischen live Update-Upload und Capgo Build.

Trigger aus der CI-Oberfläche Ausführen von Capgo Build aus der Actions-Tabelle auf Abruf.

Webhooks erstellen Starten Sie den gleichen Workflow von einem Admin-Dashboard HTTP-Anruf aus.

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

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