Automatisierte Freigaben
Tagen Sie eine Freigabe in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store übermittelt.
Ein Setup-Vorlage mit den Installationsanweisungen und der vollständigen Markdown-Dokumentation für diesen Plugin kopieren
Automate your iOS and Android builds directly from your GitHub repository. With one workflow file and a handful of repository secrets, every push, tag, or manual trigger can produce signed, store-ready apps — without anyone on the team needing a Mac, Xcode, or Android Studio installed.
Automatisierte Freigaben
Tagen Sie eine Freigabe in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store übermittelt.
Keine lokale Einrichtung
Mitwirkende auf Windows- oder Linux-Systemen können iOS-Builds auslösen. Kein Xcode, keine Bereitstellungsschwierigkeiten, keine gemeinsam genutzten Signaturzertifikate, die auf Laptops herumfliegen.
Gescannte Geheimnisse
Kredenziale leben in GitHub Repository-Geheimnissen, die auf Ihr Repository und nur auf den Workflow-Runner beschränkt sind. Leicht zu rotieren, leicht zu überprüfen.
Parallel-Builds
iOS- und Android-Builds gleichzeitig mit einem Matrix-Auftrag erstellen. Ein typischer Release dauert weniger als 10 Minuten.
Bevor Sie die Workflow-Einstellungen vornehmen, stellen Sie sicher, dass Sie haben:
bunx @capgo/cli@latest app add Build iOS and Android at the same time with a matrix job. A typical release finishes in under 10 minutes.bunx @capgo/cli@latest build init — siehe Verwaltung von Zugriffsdaten für die Schritt-für-Schritt-Anleitungbunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug— CI ist nicht der Ort, um Ihren ersten Build zu debuggengh) installiert und authentifiziert (gh auth login)Der Capgo CLI kann Ihre lokalen Anmeldeinformationen als fertig vorbereitete Datei exportieren. .env Kombiniert mit gh secret set -f, verwandelt die gesamte CI/CD-Konfiguration in drei Befehle — keine manuelle Base64-Codierung, keine JSON-Verwaltung, keine Kopieren und Einsetzen von Geheimnissen.
Fügen Sie Ihre Capgo API-Schlüssel als Repository-Geheimnis hinzu
Der API-Schlüssel gehört nicht zum Anwendungs-Keystore, also fügen Sie ihn einmal manuell ein:
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"Erstellen Sie den Schlüssel im Capgo-Dashboard Wenigstens mit den Berechtigungen hochladen oder höher. Exportieren Sie Ihre Anmeldeinformationen in ein Datei
Laufen Sie den interaktiven Anmeldeinformationen-Manager: .env Terminalfenster
Zur Zwischenablage kopieren
bunx @capgo/cli@latest build credentials manage --appId com.example.app. Die __CAPGO_KEEP_0__ schreibt mit der Modus. The CLI writes .env.capgo.<appId> with 0600 (owner-readable only) — zum Beispiel .env.capgo.com.example.app. Wenn sowohl iOS als auch Android konfiguriert sind, landen die Geheimnisse beider Plattformen in demselben Datei unter # === IOS === und # === ANDROID === Sektionenüberschriften. Die Umgebungsvariablenamen für iOS und Android sind getrennt, daher ist ihre Combination konfliktfrei.
Pushen Sie das .env Datei zu GitHub Actions-Secrets
Die gh secret set -f Kommando liest eine dotenv-Datei und erstellt eine Repository-Secret pro KEY=value Zeile:
gh secret set -f .env.capgo.com.example.appDas ist es – alle Geheimnisse Ihres Workflows befinden sich jetzt in GitHub. Überprüfen Sie mit gh secret list.
Erstelle das Workflow-File
Hinzufügen .github/workflows/capgo-build.yml zur Deiner Repository. Wähle eines der drei Triggermuster unten, je nachdem, wie du die Builds auslösen möchtest.
Zur Referenz gh secret set -f erstellt diese Repository-Geheimnisse (Deine Workflow-YAML verweist auf sie mit diesen genauen Namen):
| Plattformen | Geheime Daten, die erstellt wurden |
|---|---|
| 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 |
| (manuell hinzugefügt) | CAPGO_TOKEN |
Sie müssen diese nicht auswendig lernen – die unten stehenden Workflow-Beispiele beziehen sich bereits auf alle von ihnen.
Die drei Beispiele unten decken die häufigsten Muster ab. Sie verwenden alle die gleiche Form: Überprüfen Sie das Repository, installieren Sie die Abhängigkeiten, bauen Sie die Web-Assets, synchronisieren Sie sie mit der nativen Plattform und rufen dann Capgo Build mit übergebenen Umgebungsvariablen auf.
Erstellt einen Build, der von jedem mit Schreibzugriff ausgelöst werden kann. Aktionen Ein Reiter in GitHub mit einem Plattform-Auswahldropdown. Nützlich für ad-hoc-Testbuilds oder das Auslösen eines Releases 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 committen, gehen Sie zu Aktionen → Capgo Build (Manuell) → Workflow ausführen um es auszulösen.
Builds und versendet beide Plattformen parallel, sobald Sie eine Versions-Tag wie v1.4.0dieses ist die am häufigsten verwendete Produktionskonfiguration — git tag v1.4.0 && git push --tags Werden Sie Ihr 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 releaseDie 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 abbricht (und umgekehrt) — nützlich, wenn eine Plattform ein vorübergehendes Signierungsproblem hat.
Fängt native Build-Regressionen frühzeitig ab, indem es bei jedem Push auf ein Debug-Android-Build produziert main. Günstig, schnelle Feedback und Sie können den Upload in die Play Store 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-uploadDer paths Filter stellt sicher, dass der Workflow bei nur Dokumentationsänderungen nicht ausgeführt wird --no-playstore-upload verpasst den Upload in die Play Store (keine PLAY_CONFIG_JSON erforderlich), und --output-upload produziert eine Download-URL für das resultierende APK, damit Sie es auf einem Testgerät installieren können
Für Testversionen wird die Veröffentlichung im Store unterdrückt: Android verwendet --no-playstore-uploadfür iOS wird in Ad-hoc-Modus gebaut (was nie in den App Store hochgeladen wird). Combine entweder mit --ios-distribution ad_hoc um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten. --output-upload Die Veröffentlichung im Store zur Überprüfung einreichen
Ihr --submit-to-store-review.
Dienstkonto PLAY_CONFIG_JSON ohne explizite Spur, ohne explizite Spur, --submit-to-store-review standardmäßig auf die Produktionsstrecke mit release_status: completed. Empfehlen Sie die Angabe des Tracks am Aufrufort mit --android-track oder PLAY_STORE_TRACK, und überschreiben Sie den Status mit --android-release-status / PLAY_STORE_RELEASE_STATUS wenn erforderlich:
- 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 \ --android-track production \ --store-release-name "${GITHUB_REF_NAME}" \ --store-release-notes "Release ${GITHUB_REF_NAME}" \ --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"Für einen internen abgeschlossenen Release anstelle von Produktions:
- name: Submit Android internal release 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 \ --android-track internal \ --store-release-name "${GITHUB_REF_NAME}"iOS verwendet den App Store Connect API-Schlüsselpfad 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 ist für die App Store-Bewertung nicht erforderlich:
- 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-releaseErfolgreich --output-record <path> um das Build-Artifact-URL und QR-Code code auf dem Disk zu speichern, wenn das Build erfolgreich ist, und es dann in den folgenden Schritten mit 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 schreibt ein JSON-Record (mit jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAtund einen PNG-QR-Code code neben /tmp/build.json.qr.png. build last-output liest es zurück:
--field outputUrl druckt nur die Download-URL (Zeilenende; sicher für URL=$(...)).--field qrCodePngPath druckt den PNG-Pfad, damit Sie ihn als PR-Anhänge hochladen können.--qr druckt die renderierte ASCII-QR-Code – fügen Sie ihn in einen Markdown code-Fence in der PR-Kommentar für Inline-Scannbarkeit ein.Standardmäßig erhöht jede Release-Build die Build-Nummer. Um sie auf einen Wert zu setzen, 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-bumpbun install ist bereits schnell genug, dass ein JS-Abhängigkeitscache nur selten einen Vorteil bietet, 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') }}| Symptom | Wahrscheinliche Ursache |
|---|---|
CAPGO_TOKEN is not set | Geheime Variable nicht hinzugefügt oder Job hat keinen Zugriff darauf (Überprüfe Umgebungs-/Branchschutz) |
| Fehlende iOS- / Android-Zugangsdatenfehler | gh secret set -f war nicht ausgeführt oder wurde gegen ein anderes Repository ausgeführt. Überprüfe mit gh secret list |
cap sync fehlschlägt in CI, aber funktioniert lokal | A native Plugin ist nicht verfügbar package.jsonoder Sie haben es vergessen bun install vorher cap sync |
| Bevor Sie an einem neuen Feature arbeiten, erstellen Sie bitte ein Issue und diskutieren Sie es | Bevor Sie an einem neuen Feature arbeiten, erwähnen Sie bitte das Issue bunx @capgo/cli@latest build credentials manage |
| Die Build-Prozess ist erfolgreich, aber die App erscheint nicht in App Store Connect | Falsche Team-ID oder die App-Datei existiert noch nicht in App Store Connect. Überprüfen Sie lokal mit node_modules Die Build-Prozess hängt nach 'Projekt hochladen' |
Provisioning profile doesn't match bundle ID | Das Projektarchiv ist ungewöhnlich groß — überprüfen Sie, ob build init nicht hochgeladen wird (es sollte nicht standardmäßig hochgeladen werden) build credentials manage |
| Die Bereitstellungskarte zeigt auf eine andere Bundle-ID als die, die Xcode signiert. Rufen Sie | erneut auf, um das Profil zu aktualisieren, und exportieren Sie dann erneut mit 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. Entweder bestätigen Sie, um zu überschreiben, 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-uploadoder es scheiterte, bevor ein Artefakt erstellt wurde outputUrl wird in der Aufzeichnung null auf [ -n "$URL" ] vor seiner Verwendung |
build last-output fehlt mit Unsupported record schemaVersion | Der Runner ist auf einem älteren CLI als dem, der die Aufzeichnung 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 @latestdie sich bewegt und zwischen Aufträgen schwingen kann |
Für Plattform-spezifische Buildfehler, siehe das Troubleshooting-Leitfaden.