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 kopieren, die Installationsanweisungen und die vollständige Markdown-Dokumentation für diesen Plugin enthalten
Automatisieren Sie Ihre iOS- und Android-Builds direkt aus Ihrem GitHub-Repository. Mit einer Workflow-Datei und einigen Repository-Secrets kann jede Push, Tag oder manuelle Auslösung signierte, in den Laden lieferfähige 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 ü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
Die Anmeldeinformationen leben in den GitHub Repository-Geheimnissen, die auf Ihr Repository und nur auf den Workflow-Runner beschränkt sind. Es ist einfach, sie zu rotieren, und es ist einfach, sie zu überprüfen.
Parallel-Builds
Erstellen Sie iOS- und Android-Apps gleichzeitig mit einem Matrix-Auftrag. Ein typischer Release dauert weniger als 10 Minuten.
Eine __CAPGO_KEEP_0__-Konto mit einer aktiven Abonnement und einem __CAPGO_KEEP_1__-Schlüssel
bunx @capgo/cli@latest app add Bevor Sie die Workflow-Einstellungen vornehmen, stellen Sie sicher, dass Sie Folgendes haben:bunx @capgo/cli@latest build init — siehe Verwaltung von Anmeldedaten 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 angemeldet (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
Hinzufügen Ihres API __CAPGO_KEEP_1__-Schlüssels als Repository-Geheimnis
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 Ihrem aktuellen Verzeichnis mit Modus 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 === Sektionshauptüberschriften. Die iOS- und Android-Umgebungsvariablen sind getrennt, daher ist ihre Combination konfliktfrei.
, .env file to GitHub Actions secrets
, gh secret set -f , KEY=value ,
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.
Erstelle das Workflow-File
Hinzufügen .github/workflows/capgo-build.yml zur Deiner Repository. Wähle eine der drei Triggermuster unten aus, je nachdem, wie Du die Builds auslösen möchtest.
Zur Referenz gh secret set -f wird diese Repository-Geheimnisse (Deine Workflow-YAML referenziert sie genau mit 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 |
| (manuell hinzugefügt) | CAPGO_TOKEN |
Sie müssen diese nicht auswendig lernen – 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, native synchronisieren, dann Capgo Build mit übergebenen Umgebungsvariablen ausführen.
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 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 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 Versionsmarke wie v1.4.0__CAPGO_KEEP_0__ pushen. Dies 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 abbrechen wird (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 den Upload in die Play Store auslassen, um es rein als Rauchtest zu behalten
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 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 standardmäßig auf die Produktionsstrecke mit release_status: completed. Bei der Angabe der Strecke am Aufrufort sollte man --android-track (oder PLAY_STORE_TRACK), und überschreibt den Status mit --android-release-status / PLAY_STORE_RELEASE_STATUS wenn nötig:
- 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 anstatt der Produktionsstrecke:
- 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 die Verteilung; --ios-testflight-groups ist optional für die externe Beta-Verteilung und wird für die App Store-Bewertung 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-releaseErfolg --output-record <path> um das Build-Artifact-URL und QR-Code code auf dem Disk zu speichern, wenn der 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, finishedAt) und einen PNG-QR-Code code nebenher /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 du ihn als PR-Anhänge hochladen kannst.--qr druckt das renderierte ASCII-QR-Code — füge es in einen Markdown code-Block 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 du kontrollieren kannst (z. B. den Git-Tag), übermitteln 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ängigkeits-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-/Branchschutz) |
| 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 Fehler in CI, aber lokal funktioniert | Ein natives Plugin ist nicht vorhanden package.jsonoder Sie haben es vergessen bun install vorher cap sync |
| Erstelle ein Problem und diskutiere vorher, bevor du an einem neuen Feature arbeitest | Erwähne das Problem vorher bunx @capgo/cli@latest build credentials manage |
| Die Veröffentlichung gelingt, aber keine App erscheint in App Store Connect | Falsche Team-ID oder die App-Datei existiert noch nicht in App Store Connect. Überprüfe 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üfe, ob build init nicht hochgeladen wird (das sollte nicht der Standardfall sein) build credentials manage |
| Die Bereitstellungskarte zeigt auf eine andere Bundle-ID als die, die Xcode signiert. Führe erneut den Profil-Refresh durch, dann exportiere erneut mit | Vergessen Sie nicht, die Änderungen zu exportieren und neu 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. 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 Aufbau-Operation ist fehlgeschlagen --output-uploadoder es ist vor der Erstellung eines Artefakts gescheitert. outputUrl wird null in der Aufzeichnung. Verwenden Sie einen Zweig 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 schwimmt und zwischen den Jobs treiben kann |
Für Plattform-spezifische Build-Fehler, siehe die Troubleshooting-Anleitung.