Automatische Freigaben
Einen Release in Git tagen und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store gesendet.
Kopieren Sie einen Setup-Prompt mit den Installationsanweisungen und der vollständigen Markdown-Guideline für diesen Plugin.
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 lieferbare Apps produzieren — ohne dass jemand auf der Team ein Mac, Xcode oder Android Studio installiert hat.
Automatische Freigaben
Einen Release in Git tagen und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store gesendet.
Keine lokale Einrichtung
Mitglieder von Windows- oder Linux-Teams können iOS-Builds auslösen. Kein Xcode, keine Bereitstellungsschwierigkeiten, keine gemeinsam genutzten Signierzertifikate, die auf Laptops herumfliegen.
Gespeiste Geheimnisse
Kredenziale leben in GitHub-Repository-Secrets, skaliert auf Ihr Repository und nur für den Workflow-Runner sichtbar. Leicht zu rotieren, leicht zu überprüfen.
Parallele Builds
iOS- und Android-Builds gleichzeitig mit einem Matrix-Job erstellen. Ein typischer Release dauert unter 10 Minuten.
Bevor Sie die Workflow-Einrichtung vornehmen, stellen Sie sicher, dass Sie haben:
bunx @capgo/cli@latest app add wenn nichtbunx @capgo/cli@latest build init — siehe Managing Credentials 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 richtige 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 , verwandelt sich die gesamte CI/CD-Einrichtung in drei Befehle — keine manuelle Base64-Codierung, keine JSON-Verwaltung, keine Kopieren und Einfügen von Geheimnissen. gh secret set -fSetup
Fügen Sie Ihren Capgo API-Schlüssel als Repository-Secret hinzu
Der API-Schlüssel gehört nicht zum per-App-Zugriffsdaten-Ordner, fügen Sie ihn daher manuell hinzu:
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"Erstellen Sie den Schlüssel im Capgo-Dashboard mit Hochladen Berechtigungen oder höher.
Exportieren Sie Ihre Zugangsdaten in ein .env Datei
Führen Sie den interaktiven Zugriffsdaten-Manager aus:
bunx @capgo/cli@latest build credentials manage --appId com.example.appIn der TUI, wählen Sie Als .env exportierenDer CLI schreibt .env.capgo.<appId> in Ihrem aktuellen Verzeichnis mit der Modifikation 0600 zum Beispiel .env.capgo.com.example.appWenn sowohl iOS als auch Android konfiguriert sind, landen die Geheimnisse beider Plattformen in demselben Datei unter # === IOS === und # === ANDROID === Überschriften. Die Umgebungsvariablenamen von iOS und Android sind getrennt, daher ist ihre Combination konfliktfrei.
Schieben Sie das .env File zu GitHub Actions-Secrets
Die gh secret set -f Befehl liest eine dotenv-Datei und erstellt eine Repository-Secret pro Zeile: KEY=value Terminalfenster
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.
Terminal window
Hinzufügen .github/workflows/capgo-build.yml zu Ihrem Repository. Wählen Sie eines der drei Triggermuster unten aus, je nachdem, wie Sie Builds auslösen möchten.
Zur Referenz gh secret set -f wird diese Repository-Secrets erstellen (Ihre 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 |
Sie müssen diese nicht merken – die Workflow-Beispiele unten verweisen bereits auf alle von ihnen.
Die folgenden drei Beispiele umfassen die häufigsten 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, dann rufen Sie Capgo Build mit Umgebungsvariablen ausgeführt.
Ermöglicht es jedem mit Schreibzugriff, einen Build von der Aktionen Registerkarte in GitHub auszulösen, 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 es abgegeben haben, gehen Sie zu Aktionen → Capgo Build (Manuell) → Workflow ausführen um es auszulösen.
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 releaseDie Matrix läuft iOS und Android parallel auf separaten Ausführern. Wenn Sie fail-fast: false bedeutet, dass ein fehlgeschlagener iOS-Build den in Arbeit befindlichen Android-Build nicht abbricht (und umgekehrt) — nützlich, wenn eine Plattform vorübergehend Probleme mit der Signierung hat.
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-uploadDie paths filter stellt sicher, dass der Workflow bei nur Dokumentationsänderungen nicht ausgeführt wird. --no-playstore-upload Play Store-Submission (nicht erforderlich) und PLAY_CONFIG_JSON erzeugt eine Download-URL für das resultierende APK, damit Sie es auf einem Testgerät installieren können. --output-upload Gemeinsame Muster
; für iOS wird in Ad-hoc-Modus mit --no-playstore-upload(was nie in den App Store submitiert wird). Combine entweder mit --ios-distribution ad_hoc um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten. --output-upload __CAPGO_KEEP_0__
Standardmäßig laden Release-Builds das signierte Artefakt hoch und lassen die endgültige Ladenaktion unter Ihrer Kontrolle. Für CI-Veröffentlichungen, die direkt in den Ladenprüfungsfluss übergehen sollen, fügen Sie --submit-to-store-review.
Android verwendet Ihr PLAY_CONFIG_JSON Konto und übermittelt die Google Play-Veröffentlichung anstelle der Inaktivität. Fügen Sie --store-release-name, --store-release-notesund optionalen --store-release-notes-locale Einträge hinzu, wenn Sie die Play-Veröffentlichung mit demselben Tag und lokalisierten Änderungsprotokollen wie CI übertragen möchten:
- 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üsselpfad und übermittelt die verarbeitete TestFlight-Veröffentlichung zur App Store-Überprüfung. Es erfordert app_store Verteilung; --ios-testflight-groups ist optional für externe Beta-Verteilung und ist nicht erforderlich für die App Store-Überprüfung:
- 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-releaseErfolg --output-record <path> um das Build-Artifact-URL und QR-Code code auf dem Disk zu speichern, wenn die Build erfolgreich ist, und es dann in den folgenden Schritten wieder zu lesen, ohne 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, finishedAt) und einen PNG-QR-Code code nebenbei an /tmp/build.json.qr.png. build last-output liest es wieder:
--field outputUrl druckt nur die Download-URL (Zeilenende; sicher für URL=$(...)).--field qrCodePngPath druckt den PNG-Pfad, damit Sie ihn als Anhang für einen PR-Commit hochladen können.--qr druckt das renderierte ASCII-QR — fügen Sie es in einen Markdown-code-Fence in der PR-Kommentarein für Inline-Scannbarkeit ein.Standardmäßig erhöht jede Release-Build die Build-Nummer. Um sie auf einen Wert zu setzen, den Sie steuern können (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-bumpbun install ist bereits schnell genug, dass ein JS-Abhängigkeiten-Cache nur selten 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') }}| Symptom | Wahrscheinliche Ursache |
|---|---|
CAPGO_TOKEN is not set | Geheimer Schlüssel nicht hinzugefügt oder 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 natives Plugin ist nicht verfügbar package.jsonoder Sie haben vergessen bun install vorher cap sync |
| Der Build ist erfolgreich, 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 |
| Der Build hängt nach 'Uploading project' | Das Projektarchiv ist ungewöhnlich groß — überprüfen Sie, ob 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 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 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 ist vor der Erstellung eines Artefakts gescheitert. outputUrl wird null in der Aufzeichnung. Auf [ -n "$URL" ] bevor Sie es verwenden |
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 @latest, die schwankt und sich zwischen Aufträgen verschieben kann |
Für plattformspezifische Buildfehler, siehe das Fehlersuche-Leitfaden.