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

Voraussetzungen

Voraussetzungen

Bevor Sie die Workflow-Einrichtung vornehmen, stellen Sie sicher, dass Sie haben:

  • Ein Capgo-Konto mit einer aktiven Abonnement und einem Capgo API-Schlüssel
  • Ihre App in Capgo (bunx @capgo/cli@latest app add wenn nicht
  • Build-Zugriffskonten konfiguriert lokal mit bunx @capgo/cli@latest build init — siehe Managing Credentials für die Schritt-für-Schritt-Anleitung
  • Ein erfolgreiches lokales 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)

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

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

    Terminal-Fenster
    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.

  2. Exportieren Sie Ihre Zugangsdaten in ein .env Datei

    Führen Sie den interaktiven Zugriffsdaten-Manager aus:

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

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

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

    Zur Zwischenablage kopieren
    gh secret set -f .env.capgo.com.example.app

    That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.

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

PlattformErstellte Geheimnisse
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 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.

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

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

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

Die 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

Abschnitt mit dem Titel „Gemeinsame Muster“

Play Store / TestFlight-Upload auslassen

Abschnitt mit dem Titel „Play Store / TestFlight-Upload auslassen“

Für Testbuilds Play Store-Submission auslassen: Android verwendet

; 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__

Den Ladenveröffentlichung zur Überprüfung einreichen

Überschrift: 'Den Ladenveröffentlichung zur Überprüfung einreichen'

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

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

bun 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') }}
SymptomWahrscheinliche Ursache
CAPGO_TOKEN is not setGeheimer Schlüssel nicht hinzugefügt oder Job hat keinen Zugriff darauf (Überprüfen Sie Umgebungs-/Zweig-Schutzmaßnahmen)
Fehlende iOS/Android-Zugangsdatenfehlergh 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 funktioniertEin 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 ConnectFalsche 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 IDDer 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 fehlVergessen Sie nicht, erneut zu exportieren und erneut zu pushen: 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 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 schemaVersionDer 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.