Releases ohne Eingriff
Tagen Sie eine Release in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store gesendet.
Ein Setup-Vorschlag mit den Installations-Schritten und dem vollständigen Markdown-Leitfaden 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.
Releases ohne Eingriff
Tagen Sie eine Release in Git und Ihre signierten iOS- und Android-Binärdateien werden automatisch an TestFlight und Play Store gesendet.
Keine lokale Einrichtung
Mitwirkende auf Windows- oder Linux-Systemen können iOS-Builds auslösen. Kein Xcode, keine Bereitstellungsprobleme, keine gemeinsam genutzten Signierungszertifikate, die auf Laptops herumfliegen.
Geschachtelte Geheimnisse
Kredenziale leben in GitHub Repository-Geheimnissen, die auf Ihr Repository und nur für den Workflow-Runner sichtbar sind. Leicht zu rotieren, leicht zu überprüfen.
Parallele Builds
Bauen Sie iOS und Android gleichzeitig mit einem Matrix-Auftrag. Ein typischer Release dauert weniger als 10 Minuten.
Bevor Sie die Workflow-Einrichtung vornehmen, stellen Sie sicher, dass Sie:
bunx @capgo/cli@latest app add falls nicht)bunx @capgo/cli@latest build init — siehe Zertifikate 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 deine erste Build zu debuggengh) installiert und angemeldet (gh auth login)Das Capgo CLI kann Ihre lokalen Anmeldeinformationen als bereit zum Einsatz stehendes .env Datei. Kombiniert mit gh secret set -f, das ganze CI/CD-Setup wird in drei Befehle umgewandelt – keine manuelle Base64-Codierung, kein JSON-Hantieren, keine Kopieren und Einfügen von Geheimnissen.
Fügen Sie Ihre Capgo API-Schlüssel als Repository-Secret hinzu
Die API-Schlüssel gehört nicht zum per-App-Zugriffsstore, fügen Sie ihn also manuell hinzu:
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"Erstellen Sie die Schlüssel in der Capgo-Oberfläche mit Hochladen oder höheren Berechtigungen.
Exportieren Sie Ihre Anmeldeinformationen in eine .env Datei
Laufe den interaktiven Anmelde-Manager aus.
bunx @capgo/cli@latest build credentials manage --appId com.example.appIn der TUI auswählen Als .env-Datei exportieren. Die CLI schreibt .env.capgo.<appId> zum aktuellen Verzeichnis mit Modus 0600 (owner-lesebar nur) — zum Beispiel .env.capgo.com.example.appWenn sowohl iOS als auch Android konfiguriert sind, landen die Geheimnisse beider Plattformen in demselben Datei unter # === IOS === and # === ANDROID === Überschriften. iOS- und Android-Umgebungsvariablen sind getrennt, daher ist ihre Combination konfliktfrei.
Drücken Sie die .env Datei auf GitHub Actions-Secrets
Die gh secret set -f Kommandos liest eine dotenv-Datei und erstellt eine Repository-Secret pro KEY=value Zeile:
gh secret set -f .env.capgo.com.example.appDas ist alles — alle Geheimnisse Ihres Workflows sind jetzt in GitHub. Überprüfen Sie mit gh secret list.
Erstellen Sie das Workflow-File
Hinzufügen .github/workflows/capgo-build.yml Zu Ihrem Repository hinzufügen. Wählen Sie eines der drei Triggermuster unten aus, je nachdem, wie Sie Builds auslösen möchten.
Zur Referenz gh secret set -f erstellt diese Repository-Secrets (Ihre Workflow-YAML-Referenzen beziehen sich auf diese 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 unten stehenden Workflow-Beispiele referenzieren alle bereits.
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-Ressourcen, synchronisieren Sie sie mit der nativen, rufen Sie dann Capgo Build mit übergebenen Umgebungsvariablen auf.
Ermöglicht es jedem mit Schreibzugriff, einen Build von der Aktionen Fenster in GitHub mit einer Plattform-Auswahl. 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 with your app ID. Once committed, go to 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 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 vorübergehend Probleme mit der Signierung hat.
Fängt native Build-Regression-Fehler frühzeitig ab, indem es bei jedem Push eine Debug-Build für Android erstellt. mainBillig, 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 ensures the workflow doesn’t run on doc-only changes. --no-playstore-upload skips Play Store-Submission (kein 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 Testversionen überspringen Sie die Store-Abgabe: Android verwendet --no-playstore-upload; für iOS baut in Ad-hoc-Modus mit --ios-distribution ad_hoc (was nie dem App Store zur Verfügung stellt). Combine entweder mit --output-upload um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten.
Standardmäßig laden Release-Builds das signierte Artefakt hoch und lassen die endgültige Store-Aktion unter Ihrer Kontrolle. Für CI-Veröffentlichungen, die direkt in den Store-Review-Flow gelangen sollen, fügen Sie --submit-to-store-review.
Android verwendet Ihr PLAY_CONFIG_JSON Dienstkonto. Ohne explizite Spur --submit-to-store-review setzt sich auf die Produktions-Spur mit release_status: completed. Empfehlen Sie, die Spur am Aufrufort zu angeben 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 eine interne abgeschlossene Veröffentlichung anstatt der Produktions-Spur:
- 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 die App Store Connect API Schlüsselverbindung und sendet die bearbeitete TestFlight-Version zur App Store-Bewertung. Es erfordert app_store Verteilung; --ios-testflight-groups ist optional für 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 auf der Festplatte zu speichern, wenn die 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 eine JSON-Datei (mit jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) und einen PNG-QR-Code code nebenbei /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 PR-Anhänge hochladen können.--qr druckt den renderierten ASCII-QR-Code — fügen Sie ihn in einen Markdown-code-Block in der PR-Kommentarzeile ein, um Inline-Scannbarkeit zu ermöglichen.Standardmäßig erhöht sich bei jeder Release-Veröffentlichung die Buildnummer. Um sie auf einen Wert festzulegen, den Sie kontrollieren (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 selten rentabel ist, 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 wurde nicht hinzugefügt oder der Job hat keinen Zugriff darauf (Überprüfe Umgebungs-/Branch-Schutz) |
| Fehlende iOS- / Android-Zugangsdatenfehler | gh secret set -f hat nicht läuft, oder wurde gegen eine andere Repository ausgeführt. Überprüfen Sie mit gh secret list |
cap sync fehlt in CI, aber funktioniert lokal | Ein natives Plugin ist nicht in package.jsonoder Sie haben es vergessen bun install vorher cap sync |
| Die Build ist erfolgreich, aber die App erscheint nicht 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 |
| Build hängt nach „Projekt hochladen“ | Projektarchiv ist ungewöhnlich groß — überprüfen Sie das node_modules wird nicht hochgeladen (es sollte nicht standardmäßig sein) |
Provisioning profile doesn't match bundle ID | Die Bereitstellungsmap zeigt auf einen anderen Bundle-Id als der, den Xcode signiert. Laufe erneut ab build init um das Profil zu aktualisieren, exportiere dann erneut mit build credentials manage |
| Benutzerkonto wurde lokal geändert, aber CI fehlschlägt immer noch | 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 | Konfigurations-Schlüssel werden zwischen Plattformen unterschiedlich behandelt – der Manager warnt und fragt nach Bestätigung. Bestätigen Sie, um zu überschreiben, oder exportieren Sie pro Plattform neu. --platform ios / --platform android |
build last-output druckt eine leere URL | Die Build schlug fehl --output-uploadoder es schlug fehl, bevor ein Artefakt erstellt wurde outputUrl wird null in der Aufzeichnung. Branch auf [ -n "$URL" ] vor seiner Verwendung |
build last-output Fehler mit Unsupported record schemaVersion | Der Runner ist auf einem älteren CLI als dem, der das Protokoll geschrieben hat. Pin sowohl Produzent als auch Leser auf die gleiche explizite Version (z.B. bunx @capgo/cli@7.104.0 … auf beiden Seiten) anstatt @latest, das schwimmt und zwischen den Aufträgen treiben kann |
Für plattformspezifische Build-Fehler siehe die Troubleshooting-Anleitung.