Zum Inhalt springen

GitHub Aktionen

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

  • Ihr App registriert in Capgo ( Capgo API key
  • Your app registered in Capgo (bunx @capgo/cli@latest app add Bevor Sie die Workflow-Einstellungen vornehmen, stellen Sie sicher, dass Sie Folgendes haben:
  • Baumusterkennungen, die lokal konfiguriert sind, mit bunx @capgo/cli@latest build init — siehe Verwaltung von Anmeldedaten 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 angemeldet (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

    Hinzufügen Ihres API __CAPGO_KEEP_1__-Schlüssels als Repository-Geheimnis

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

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

  3. , .env file to GitHub Actions secrets

    , gh secret set -f , KEY=value ,

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

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

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

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

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

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

Abschnitt mit dem Titel ‘Lesen Sie die Ausgabeadresse des Builds und den QR-Code code’

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

bun 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') }}

Fehlende Cache-Wiederherstellung: Falsche Cache-Wiederherstellung

Bereich mit dem Titel "Fehlende Cache-Wiederherstellung"
SymptomWahrscheinliche Ursache
CAPGO_TOKEN is not setGeheimer Schlüssel nicht hinzugefügt oder Job hat keinen Zugriff darauf (Überprüfen Sie Umgebungs-/Branchschutz)
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 Fehler in CI, aber lokal funktioniertEin 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 arbeitestErwähne das Problem vorher bunx @capgo/cli@latest build credentials manage
Die Veröffentlichung gelingt, aber keine App erscheint in App Store ConnectFalsche 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 IDDas 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 mitVergessen 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 schreibenDie 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 ausDie 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 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 schwimmt und zwischen den Jobs treiben kann

Für Plattform-spezifische Build-Fehler, siehe die Troubleshooting-Anleitung.