Zum Inhalt springen

GitHub Aktionen

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:

  • Eine Capgo-Konto mit einer aktiven Abonnement und einem Capgo API-Schlüssel
  • Ihr App registriert in Capgo (bunx @capgo/cli@latest app add falls nicht)
  • Mit lokalen Zugriffskonten konfiguriert bunx @capgo/cli@latest build init — siehe Zugriffskonten verwalten für die Schritt-für-Schritt-Anleitung
  • Ein erfolgreicher lokaler Build (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug— CI ist nicht der richtige Ort, um Ihren ersten Build zu debuggen
  • Die GitHub CLI (gh) installiert und authentifiziert (gh auth login)

Einstellungen

Einstellungen

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

  1. Add your Capgo API key as a repository secret

    Fügen Sie Ihre API __CAPGO_KEEP_1__-Schlüssel als Repository-Geheimnis hinzu

    Der __CAPGO_KEEP_0__-Schlüssel gehört nicht zum Anwendungs-Keystore, also fügen Sie ihn einmal manuell ein:
    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.

  2. Exportieren Sie Ihre Anmeldeinformationen in ein .env Datei

    Führen Sie den interaktiven Anmeldeinformationen-Manager aus:

    Terminalfenster
    bunx @capgo/cli@latest build credentials manage --appId com.example.app

    In 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.

  3. 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:

    Terminalfenster
    gh secret set -f .env.capgo.com.example.app

    Das ist es — alle Geheimnisse, die Ihr Workflow benötigt, sind jetzt in GitHub. Überprüfen Sie mit gh secret list.

  4. 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):

PlattformGeheime Daten erstellt
iOSBUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
AndroidANDROID_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.

github/workflows/capgo-build-manual.yml
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.

github/workflows/capgo-build-release.yml
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 release

Die 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

github/workflows/capgo-build-main.yml
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-upload

Der 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

Play Store / TestFlight-Upload überspringen

Sektion: Play Store / TestFlight-Upload überspringen

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.

Die Veröffentlichung im Store zur Überprüfung einreichen

Sektion: Die Veröffentlichung im Store zur Überprüfung einreichen

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-release

Lesen Sie die Ausgabeadresse des Builds und den QR-Code code

Sektion mit dem Titel “Lesen Sie die Ausgabeadresse des Builds und den QR-Code code”

Passieren --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-bump

bun 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') }}
SymptomWahrscheinliche Ursache
CAPGO_TOKEN is not setGeheime Variable nicht hinzugefügt oder Job hat keinen Zugriff darauf (Überprüfen Sie Umgebungs- bzw. Branchenschutz)
Fehlende iOS- / Android-Zugangsdatenfehlergh 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 lokalA 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 esBevor 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 ConnectFalsche 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 IDDas 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 erneutum das Profil zu aktualisieren, dann exportieren Sie erneut mit bunx @capgo/cli@latest build credentials managegh secret set -f .env.capgo.<appId>
Der Manager weigert sich, das kombinierte Datei zu schreibenDie 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 ausDie 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 schemaVersionDer 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.