Automatisierte Freigaben
Tagen Sie eine Freigabe in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store gesendet.
Eine Setup-Anweisung mit den Installationsanweisungen und der vollständigen Markdown-Dokumentation für diesen Plugin kopieren
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 erzeugen – ohne dass jemand auf der Team ein Mac, Xcode oder Android Studio installiert hat.
Automatisierte Freigaben
Tagen Sie eine Freigabe in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store gesendet.
Keine lokale Einrichtung
Mitglieder auf Windows- oder Linux-Systemen können iOS-Builds auslösen. Kein Xcode, keine Bereitstellungsschwierigkeiten, keine gemeinsam genutzten Signierungszertifikate, die auf Laptops herumfliegen.
Beschränkte Geheimnisse
Die Anmeldeinformationen befinden sich im GitHub Repository-Geheimnis und sind auf Ihr Repository beschränkt und nur für den Workflow-Runner sichtbar. Es ist einfach, sie zu rotieren, und es ist einfach, sie zu überprüfen.
Parallele Builds
Erstellen Sie iOS- und Android-Apps gleichzeitig mit einem Matrix-Auftrag. Ein typischer Release dauert weniger als 10 Minuten.
Bevor Sie die Workflow-Einstellungen vornehmen, stellen Sie sicher, dass Sie Folgendes haben:
bunx @capgo/cli@latest app add falls nicht)bunx @capgo/cli@latest build init — siehe Zugriffskonten verwalten 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)The Capgo CLI can export your local credentials as a ready-to-use .env Der __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ kann Ihre lokalen Anmeldeinformationen als bereit zum Einsatz stehendes Datei exportieren. gh secret set -fKombiniert mit
Add your Capgo API key as a repository secret
Fügen Sie Ihre API __CAPGO_KEEP_1__-Schlüssel als Repository-Geheimnis hinzu
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"Zwischenablage kopieren Erstellen Sie den Schlüssel im Capgo-Dashboard mit Hochladen Berechtigungen 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 Exportieren Sie in .env. Die CLI schreibt .env.capgo.<appId> in Ihr aktuelles Verzeichnis mit Modus 0600 (Eigentümer-lesbar nur) — 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 iOS- und Android-Umgebungsvariablen 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, die Ihr Workflow benötigt, sind jetzt in GitHub. Überprüfen Sie mit gh secret list.
Erstelle das Workflow-File
Hinzufügen .github/workflows/capgo-build.yml zur deinen 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 erstellt diese Repository-Geheimnisse (Ihre Workflow-YAML-Referenzen sie genau nach diesen Namen):
| Plattform | Geheime Daten erstellt |
|---|---|
| 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 sich diese nicht merken – die unten stehenden 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, nativ synchronisieren, dann Capgo mit Benutzerdaten als Umgebungsvariablen aufrufen.
Ermöglicht es jedem mit Schreibzugriff, einen Build von der Aktionen Ein Reiter in GitHub mit einem Plattform-Auswahldropdown. Nützlich für ad-hoc-Testbuilds oder das Auslösen eines Releases auf Abruf.
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 diese geändert haben, 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.0Dies ist die am häufigsten verwendete Produktionskonfiguration — git tag v1.4.0 && git push --tags Wird zu deinem 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 ein Debug-Build für Android auf jedem Push erstellt wird main. Günstig, schnelle Feedback und Sie können die Veröffentlichung im 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 die Veröffentlichung im Play Store (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
Für Testversionen wird die Veröffentlichung im Store unterdrückt: Android verwendet --no-playstore-upload; fü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.
Standardmäßig werden Release-Builds das signierte Artefakt hochladen und die endgültige Store-Aktion unter Ihrer Kontrolle lassen. 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. Ohne explizite Spur, --submit-to-store-review wird standardmäßig auf die Produktionsstrecke gesetzt mit release_status: completed. Empfehlen Sie die Angabe der Strecke am Aufrufort mit --android-track oder, und überschreiben Sie den Status mit PLAY_STORE_TRACKwenn erforderlich: --android-release-status / PLAY_STORE_RELEASE_STATUS Zurücksetzen in die Zwischenablage
- 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}"Zurücksetzen in die Zwischenablage
- 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 uses the App Store Connect API key path and submits the processed TestFlight build to App Store review. It requires app_store ist optional für externe Beta-Verteilung und wird nicht für die App Store-Bewertung benötigt: --ios-testflight-groups Zurücksetzen in die Zwischenablage
- 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-releasePassieren --output-record <path> um die Ausgabeadresse des Builds und den QR-Code code auf dem Disk zu speichern, wenn der Build erfolgreich ist, und es dann in den folgenden Schritten wieder zu lesen, ohne dass es zu Log-Scraping oder Regex kommt. build last-outputZwischenablage kopieren
- 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 es wieder zurück liest: jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) and a PNG QR code alongside at /tmp/build.json.qr.png. build last-output reads it back:
--field outputUrl druckt nur die Download-URL (Zeilenende; sicher für URL=$(...)).--field qrCodePngPath druckt den PNG-Pfad, damit du ihn als PR-Anhänge hochladen kannst.--qr druckt das renderierte ASCII-QR-Code — füge es in einen Markdown code-Fence in der PR-Kommentar für Inline-Scannbarkeit ein.Standardmäßig erhöht jede Release-Build die Buildnummer. Um sie auf einen Wert zu setzen, den du kontrollierst (z. B. den Git-Tag), übergebe --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 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üfen Sie Umgebungs- bzw. Branchenschutz) |
| Fehlende iOS- / Android-Zugangsdatenfehler | gh secret set -f hat nicht läuft oder wurde gegen ein anderes Repository ausgeführt. Überprüfen Sie 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 ein Issue und diskutieren Sie es | Bevor Sie an einem neuen Feature arbeiten, erwähnen Sie das Issue bunx @capgo/cli@latest build credentials manage |
| Die Veröffentlichung gelingt, 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 Veröffentlichung hängt nach 'Projekt hochladen' |
Provisioning profile doesn't match bundle ID | Das Projektarchiv ist ungewöhnlich groß — überprüfen Sie, dass build init nicht hochgeladen wird (das sollte nicht der Standardfall sein) build credentials manage |
| Die Bereitstellungsmap zeigt auf eine andere Bundle-ID als die, die Xcode signiert. Führen Sie erneut | um das Profil zu aktualisieren, dann exportieren Sie 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 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 beide Produzent und Leser auf die gleiche explizite Version (z.B. bunx @capgo/cli@7.104.0 … auf beiden Seiten) anstatt @latest, die schwankt und zwischen den Aufträgen treiben kann |
For Plattform-spezifischen Build-Fehlern, siehe die Troubleshooting-Anleitung.