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 Workflowdatei und einigen Repositorygeheimnissen können Sie mit jedem Push, Tag oder manuellen Trigger signierte, in den Laden lieferbare Apps erzeugen — ohne dass jemand auf der Teammitglieder einen Mac, Xcode oder Android Studio installieren muss.

Was Sie erhalten

Hands-off 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 des Teams auf Windows- oder Linux-Systemen können iOS-Builds auslösen. Kein Xcode, keine Bereitstellungshasseln, 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

iOS und Android gleichzeitig mit einem Matrix-Auftrag 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 Voraussetzungen Kontomanagement für die Zauberer-Walkthrough
Ein 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

Die Capgo CLI kann Ihre lokalen Anmeldeinformationen als fertig vorbereitete Datei exportieren. .env Kombiniert mit gh secret set -fdiesem wird die gesamte CI/CD-Konfiguration in drei Befehle umgewandelt – keine manuelle Base64-Codierung, keine JSON-Verwaltung, keine Kopieren und Einfügen von Geheimnissen.

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

Die API-Schlüssel sind nicht Teil der Anwendungs-credential-Speicherung, daher müssen Sie sie einmal manuell hinzufügen:
Terminal-Fenster
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Erstellen Sie den Schlüssel im Capgo-Dashboard mit Hochladen 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 In .env exportieren . Die CLI schreibt .env.capgo.<appId> in Ihr aktuelles Verzeichnis mit Modus 0600 (Eigner-Leseberechtigung nur) — 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 sind getrennt, daher ist ihre Combination konfliktfrei.

Übernehmen --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 einen Widerspruch findet, druckt er die konfligierenden Schlüssel aus, fragt nach expliziter Bestätigung, bevor er schreibt, und fügt die Konfliktliste als Kommentar an der Spitze der Datei ein. Re-export mit --platform Wenn Sie Werte pro Plattform beibehalten müssen.
Pushen Sie das .env Datei zu GitHub Actions-Secrets

Das gh secret set -f Befehl liest eine dotenv-Datei und erstellt eine Repository-Secret pro Zeile: KEY=value Terminal-Fenster
Zur Vervollständigung 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 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 Ihrem Repository. Wählen Sie eines der drei Auslösermuster unten aus, je nachdem, wie Sie Builds auslösen möchten.

Was in Ihren Geheimnissen landet

wird diese Repository-Secrets (Ihre Arbeitsablauf-YAML verweist auf sie unter diesen genauen Namen) erstellen: gh secret set -f Plattform

Erstellte Geheimnisse	Secrets created
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 die gleiche 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 übergebenen Umgebungsvariablen auf.

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 on Push to Main

Fängt native Build-Regressionen frühzeitig ab, indem es bei jedem Push auf die Hauptverbindung einen Debug-Android-Build erstellt. 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 die Workflow nicht auf doc-only-Änderungen läuft. --no-playstore-upload Play Store-Submission (keine PLAY_CONFIG_JSON benötigt) und --output-upload produziert 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, Submission an den App Store auslassen: Android verwendet --no-playstore-upload; für iOS, in Ad-hoc-Modus mit --ios-distribution ad_hoc (was nie an den App Store submitiert). Combine entweder mit --output-upload um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten.

Lese die Ausgabeadresse der Build-URL und QR code

Pass --output-record <path> um die Build-Artikel-URL und QR code zu persistieren, wenn die Build erfolgreich ist, und es dann in nachfolgenden Schritten mit build last-outputzu lesen. Keine 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 schreibt ein JSON-Record (mit jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) und eine PNG-QR code nebenan /tmp/build.json.qr.png. build last-output liest es wieder zurück:

--field outputUrl druckt nur die Download-URL (Zeilenende; sicher für URL=$(...)).
--field qrCodePngPath druckt den PNG-Pfad, damit du ihn als PR-Anhängung hochladen kannst.
--qr druckt das renderierte ASCII-QR — füge es in einen Markdown code-Fence in der PR-Kommentar ein, um Inline-Scannbarkeit zu ermöglichen.

Ü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 du kontrollieren kannst (z.B. den Git-Tag), übergebe man --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

bun install ist bereits so schnell, dass ein JS-Abhängigkeitscache nur selten rentiert, 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') }}

Fehlersuche

Symptom	Wahrscheinliche Ursache
`CAPGO_TOKEN is not set`	Geheimes nicht hinzugefügt oder Job hat keinen Zugriff darauf (Überprüfen Sie Umgebungs-/Branch-Schutzmechanismen)
Fehlende iOS / Android-Zugangsfehler	`gh secret set -f` wurde nicht ausgeführt oder wurde gegen eine andere Repository ausgeführt. Überprüfen Sie mit `gh secret list`
`cap sync` Fehlschlägt in CI, aber funktioniert lokal	Eine native Plugin ist nicht verfügbar `package.json`oder Sie haben vergessen `bun install` vorher `cap sync`
Der Build gelingt, aber keine App erscheint in App Store Connect	Falsche Team-ID, oder die App-Eintrag 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, dass `node_modules` nicht hochgeladen wird (es sollte nicht standardmäßig sein)
`Provisioning profile doesn't match bundle ID`	Der Provisioning-Map zeigt auf eine andere Bundle-ID als die, die Xcode signiert. Rufen Sie `build init` erneut auf, um das Profil zu aktualisieren, dann exportieren Sie erneut mit `build credentials manage`
Die lokalen Anmeldedaten wurden geändert, aber CI schlägt immer noch fehl	Don’t forget to re-export and re-push: `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Der Manager weigert sich, das kombinierte Datei zu schreiben	Die Konfigurations-Schlüssel sind zwischen Plattformen unterschiedlich – der Manager warnt und fragt nach Bestätigung. Entweder bestätigen Sie, um zu übernehmen, oder exportieren Sie pro Plattform neu mit `--platform ios` / `--platform android`
`build last-output` druckt eine leere URL aus	Die Verarbeitung war nicht erfolgreich `--output-upload`oder es ist vor der Erstellung eines Artefakts gescheitert. `outputUrl` werden `null` im Protokoll. Auf `[ -n "$URL" ]` vor seiner Verwendung
`build last-output` fehlt mit `Unsupported record schemaVersion`	Der Runner ist auf einem älteren CLI als dem, der das Protokoll geschrieben hat. Pinnen Sie sowohl Produzent als auch Leser auf die gleiche explizite Version (z.B. `bunx @capgo/cli@7.104.0 …` auf beiden Seiten) anstatt `@latest`die sich zwischen den Aufgaben bewegen können

Für Plattformspezifische Buildfehler siehe die Troubleshooting-Anleitung.

Zukünftige 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-Handling.

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