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.

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:

  • Aktiv Capgo-Konto mit einer laufenden Abonnement und einem Capgo API-Schlüssel
  • Deine App registriert in Capgo (bunx @capgo/cli@latest app add falls nicht)
  • Build-Zertifikate konfiguriert lokal mit bunx @capgo/cli@latest build init — siehe Zertifikate verwalten für die Schritt-für-Schritt-Anleitung
  • Erfolgreiche lokale Build (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI ist nicht der richtige Ort, um deine erste Build zu debuggen
  • Die GitHub CLI (gh) 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.

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

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

  2. Exportieren Sie Ihre Anmeldeinformationen in eine .env Datei

    Laufe den interaktiven Anmelde-Manager aus.

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

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

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

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

    Das ist alles — alle Geheimnisse Ihres Workflows sind jetzt in GitHub. Überprüfen Sie mit gh secret list.

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

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

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

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

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

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

Skip Buildnummer erhöhen

Abschnitt: Skip Buildnummer erhöhen

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

bun 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') }}
SymptomWahrscheinliche Ursache
CAPGO_TOKEN is not setGeheimer Schlüssel wurde nicht hinzugefügt oder der Job hat keinen Zugriff darauf (Überprüfe Umgebungs-/Branch-Schutz)
Fehlende iOS- / Android-Zugangsdatenfehlergh 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 lokalEin 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 IDDie 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 schreibenKonfigurations-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 URLDie 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 schemaVersionDer 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.