Zum Inhalt springen

GitHub Aktionen

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.

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

Kredenziale leben in GitHub Repository-Geheimnissen, die auf Ihr Repository und nur auf den Workflow-Runner beschränkt sind. Leicht zu rotieren, leicht zu überprüfen.

Parallel-Builds

iOS- und Android-Builds gleichzeitig mit einem Matrix-Auftrag erstellen. Ein typischer Release dauert weniger als 10 Minuten.

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

  • Ein Capgo-Konto mit einer aktiven Abonnement und einem __CAPGO_KEEP_1__-Schlüssel Capgo API key
  • Credentials live in Capgo repository secrets, scoped to your repo and visible only to the workflow runner. Easy to rotate, easy to audit.bunx @capgo/cli@latest app add Build iOS and Android at the same time with a matrix job. A typical release finishes in under 10 minutes.
  • Baumusterkredenziale, die lokal konfiguriert sind mit bunx @capgo/cli@latest build init — siehe Verwaltung von Zugriffsdaten 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 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. .env Kombiniert mit gh secret set -f, verwandelt die gesamte CI/CD-Konfiguration in drei Befehle — keine manuelle Base64-Codierung, keine JSON-Verwaltung, keine Kopieren und Einsetzen von Geheimnissen.

  1. Fügen Sie Ihre Capgo API-Schlüssel als Repository-Geheimnis hinzu

    Der API-Schlüssel gehört nicht zum Anwendungs-Keystore, also fügen Sie ihn einmal manuell ein:

    Terminalfenster
    gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

    Erstellen Sie den Schlüssel im Capgo-Dashboard Wenigstens mit den Berechtigungen hochladen oder höher. Exportieren Sie Ihre Anmeldeinformationen in ein Datei

  2. Laufen Sie den interaktiven Anmeldeinformationen-Manager: .env Terminalfenster

    Zur Zwischenablage kopieren

    Wählen Sie in der TUI
    bunx @capgo/cli@latest build credentials manage --appId com.example.app

    . Die __CAPGO_KEEP_0__ schreibt mit der Modus. The CLI writes .env.capgo.<appId> with 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 === Sektionenüberschriften. Die Umgebungsvariablenamen für iOS und Android 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 Ihres Workflows befinden sich jetzt in GitHub. Überprüfen Sie mit gh secret list.

  4. Erstelle das Workflow-File

    Hinzufügen .github/workflows/capgo-build.yml zur Deiner Repository. Wähle eines der drei Triggermuster unten, je nachdem, wie du die Builds auslösen möchtest.

Zur Referenz gh secret set -f erstellt diese Repository-Geheimnisse (Deine Workflow-YAML verweist auf sie mit diesen genauen Namen):

PlattformenGeheime Daten, die erstellt wurden
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
(manuell hinzugefügt)CAPGO_TOKEN

Sie müssen diese nicht auswendig lernen – die unten stehenden Workflow-Beispiele beziehen sich bereits auf alle von ihnen.

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-Assets, synchronisieren Sie sie mit der nativen Plattform und rufen dann Capgo Build mit übergebenen Umgebungsvariablen auf.

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 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 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 Versions-Tag wie v1.4.0dieses ist die am häufigsten verwendete Produktionskonfiguration — git tag v1.4.0 && git push --tags Werden Sie Ihr 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 es bei jedem Push auf ein Debug-Android-Build produziert main. Günstig, schnelle Feedback und Sie können den Upload in die 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 den Upload in die Play Store (keine PLAY_CONFIG_JSON erforderlich), und --output-upload produziert eine Download-URL für das resultierende APK, damit Sie es auf einem Testgerät installieren können

Play Store / TestFlight-Upload überspringen

Abschnitt: "Play Store / TestFlight-Upload überspringen"

Für Testversionen wird die Veröffentlichung im Store unterdrückt: Android verwendet --no-playstore-uploadfür iOS wird in Ad-hoc-Modus gebaut (was nie in den App Store hochgeladen wird). Combine entweder mit --ios-distribution ad_hoc um eine zeitbegrenzte Download-URL für das Binärdatei zu erhalten. --output-upload Die Veröffentlichung im Store zur Überprüfung einreichen

Ihr --submit-to-store-review.

Dienstkonto PLAY_CONFIG_JSON ohne explizite Spur, ohne explizite Spur, --submit-to-store-review standardmäßig auf die Produktionsstrecke mit release_status: completed. Empfehlen Sie die Angabe des Tracks am Aufrufort 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 einen internen abgeschlossenen Release anstelle von Produktions:

- 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 Verteilung; --ios-testflight-groups ist optional für externe Beta-Verteilung und ist für die App Store-Bewertung nicht erforderlich:

- 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

Erfolgreich --output-record <path> um das Build-Artifact-URL und QR-Code code auf dem Disk zu speichern, wenn das 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, finishedAtund einen PNG-QR-Code code neben /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 Sie ihn als PR-Anhänge hochladen können.
  • --qr druckt die renderierte ASCII-QR-Code – fügen Sie ihn in einen Markdown code-Fence 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 Sie kontrollieren (z. B. den Git-Tag), übergeben 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ängigkeitscache 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üfe Umgebungs-/Branchschutz)
Fehlende iOS- / Android-Zugangsdatenfehlergh secret set -f war nicht ausgeführt oder wurde gegen ein anderes Repository ausgeführt. Überprüfe 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 bitte ein Issue und diskutieren Sie esBevor Sie an einem neuen Feature arbeiten, erwähnen Sie bitte das Issue bunx @capgo/cli@latest build credentials manage
Die Build-Prozess ist erfolgreich, 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 Build-Prozess hängt nach 'Projekt hochladen'
Provisioning profile doesn't match bundle IDDas Projektarchiv ist ungewöhnlich groß — überprüfen Sie, ob build init nicht hochgeladen wird (es sollte nicht standardmäßig hochgeladen werden) build credentials manage
Die Bereitstellungskarte zeigt auf eine andere Bundle-ID als die, die Xcode signiert. Rufen Sieerneut auf, um das Profil zu aktualisieren, und exportieren Sie dann 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 wird in der Aufzeichnung null auf [ -n "$URL" ] vor seiner Verwendung
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 @latestdie sich bewegt und zwischen Aufträgen schwingen kann

Für Plattform-spezifische Buildfehler, siehe das Troubleshooting-Leitfaden.