Hands-free Releases
Tagen Sie eine Release in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store übermittelt.
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 einem Workflow-File und einer Handvoll Repository-Secrets können alle Pushs, Tags oder manuellen Trigger signierte, in den Laden lieferbare Apps erzeugen — ohne dass jemand auf der Team ein Mac, Xcode oder Android Studio installiert hat.
Hands-free 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 Bereitstellungshassels, keine gemeinsam genutzten Signierungszertifikate, die auf Laptops herumfliegen.
Gesicherte Geheimnisse
Daten leben in GitHub Repository-Secrets, abgesichert auf Ihrem Repository und nur für den Workflow-Runner sichtbar. Leicht zu rotieren, leicht zu überprüfen.
Parallel Builds
Mit einem Matrix-Auftrag iOS und Android gleichzeitig bauen. Ein typischer Release dauert unter 10 Minuten.
Bevor Sie die Workflow-Einstellungen vornehmen, stellen Sie sicher, dass Sie haben:
bunx @capgo/cli@latest app add falls nichtbunx @capgo/cli@latest build init — siehe Kontenverwaltung für die Zauberer-Walkthroughbunx @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. 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 Ihre __CAPGO_KEEP_0__ __CAPGO_KEEP_1__-Schlüssel als Repository-Geheimnis 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:
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"__CAPGO_KEEP_0__-Dashboard Capgo dashboard Hochladen Add your __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ key as a repository secret Rechte oder höher.
Exportieren Sie Ihre Anmeldeinformationen in ein .env Datei
Führen Sie den interaktiven Anmeldeinformationen-Manager aus:
bunx @capgo/cli@latest build credentials manage --appId com.example.appIn der TUI wählen Sie Zur .env-Datei exportieren. Die CLI schreibt .env.capgo.<appId> mit Modus 0600 (Eigner-Leseberechtigung) — 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 === Sektionsüberschriften. iOS- und Android-Umgebungsvariablen sind disjunkt, 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 Zeile: KEY=value Fenster des Terminal
gh secret set -f .env.capgo.com.example.appThat’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.
Arbeitsablaufdatei erstellen
Hinzufügen .github/workflows/capgo-build.yml in Ihr Repository. Wählen Sie eines der drei Triggermuster unten aus, je nachdem, wie Sie die Builds auslösen möchten.
Zum Verweis gh secret set -f wird diese Repository-Secrets erstellen (Ihr 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.
Die drei Beispiele unten decken die häufigsten Muster ab. Sie verwenden alle die gleiche Form: Repository auschecken, Abhängigkeiten installieren, Web-Assets erstellen, auf nativ synchronisieren, dann Capgo mit Übergebene Umgebungsvariablen Build ausführen.
Ermöglicht es jedem mit Schreibzugriff, einen Build von der Aktionen Registerkarte in GitHub auszuführen, wobei eine Plattform auswählbar ist. 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.
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 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 Main 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-uploadDie paths Der Filter stellt sicher, dass der Workflow nicht auf doc-only-Änderungen läuft. --no-playstore-upload Play Store-Submission (keine PLAY_CONFIG_JSON benötigt) und --output-upload erzeugt eine Download-URL für das resultierende APK, damit Sie es auf einem Testgerät installieren können.
Für Testbuilds, Submission in den App Stores überspringen: Android verwendet --no-playstore-upload; für iOS, 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.
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 übermittelt die Google Play-Veröffentlichung anstatt es inaktiv zu lassen. 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 Changelogs 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 den App Store Connect API-Schlüsselweg und sendet die verarbeitete TestFlight-Version zum App Store-Review. app_store Verteilung; --ios-testflight-groups ist optional für externe Beta-Verteilung und wird für den App Store-Review nicht 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-releaseErfolgreich --output-record <path> persistiert die Ausgabeadresse des Builds und QR-Code code auf der Festplatte, wenn die Build erfolgreich ist, und liest sie dann in den folgenden Schritten wieder, ohne Log-Scraping oder Regex. build last-outputErfolgreich
- 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 ein PNG-QR-code-Code nebenbei schreibt /tmp/build.json.qr.png. build last-output es liest es wieder ein:
--field outputUrl nur die Download-URL (neuer Zeilenende; sicher für URL=$(...)).--field qrCodePngPath den PNG-Pfad gibt es, damit Sie ihn als PR-Anhänge hochladen können.--qr den renderierten ASCII-QR-Code druckt — fügen Sie ihn in einen Markdown-code-Fence in die PR-Kommentarzeile für Inline-Scannbarkeit ein.Standardmäßig erhöht sich bei jeder Release-Ausgabe die Buildnummer. Um sie auf einen Wert festzulegen, 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 so schnell, dass ein JS-Abhängigkeiten-Cache nur selten einen Vorteil bietet, 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') }}| Symptom | Wahrscheinliche Ursache |
|---|---|
CAPGO_TOKEN is not set | Geheimnis wurde nicht hinzugefügt oder der Job hat keinen Zugriff darauf (Überprüfen Sie Umgebungs-/Zweig-Schutzmaßnahmen) |
| Fehlende iOS / Android-Zugangsdatenfehler | 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 Funktioniert nicht in CI, aber lokal funktioniert | Ein nativer Plugin ist in package.json, oder Sie haben es 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üfen Sie lokal mit bunx @capgo/cli@latest build credentials manage |
| Die Veröffentlichung hängt nach „Projekt hochladen“ | Das Projektarchiv ist ungewöhnlich groß — überprüfen Sie, dass node_modules wird nicht hochgeladen (es sollte nicht standardmäßig hochgeladen werden) |
Provisioning profile doesn't match bundle ID | The Provisionierungsmap zeigt auf einen anderen Bundle-Id als der, den Xcode signiert. Lauf erneut build init um das Profil zu aktualisieren, dann exportiere erneut mit build credentials manage |
| Die lokalen Anmeldedaten wurden geändert, aber CI schlägt immer noch fehl | Vergiss nicht, erneut zu exportieren und 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. Entweder bestätige, um eins-gewinnt zu übernehmen, oder exportiere pro-Plattform erneut mit --platform ios / --platform android |
build last-output druckt eine leere URL | Die Verarbeitung schlug fehl --output-uploadoder es schlug fehl, bevor ein Artefakt produziert wurde. outputUrl werden null im Protokoll. Branch auf [ -n "$URL" ] vor seiner 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 denselben expliziten 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.