Passer à la navigation principale

Actions GitHub

Automatisez vos builds iOS et Android directement à partir de votre GitHub repository. Avec un fichier de workflow unique et quelques secrets de repository, chaque push, tag ou déclencheur manuel peut produire des applications signées et prêtes à être stockées — sans qu'aucun membre de l'équipe n'a besoin d'un Mac, d'Xcode ou d'Android Studio installés.

Sorties sans intervention

Marquez une sortie dans Git et vos binaires iOS et Android signés sont soumis automatiquement à TestFlight et à la Play Store.

Aucune configuration locale

Les contributeurs sur Windows ou Linux peuvent déclencher des builds iOS. Pas besoin de Xcode, pas de problèmes de provisioning, pas de certificats de signature partagés qui flottent sur les ordinateurs portables.

Secrets étendus

Les informations d'identification vivent dans les secrets de répertoire GitHub, étendus à votre répertoire et visibles uniquement pour l'exécuteur de workflow. Facile à mettre à jour, facile à auditor.

Constructions parallèles

Construire iOS et Android en même temps avec un travail de matrice. Une mise à jour typique se termine en moins de 10 minutes.

Avant de configurer le flux de travail, assurez-vous d'avoir :

  • Un compte Capgo avec une souscription active et une Capgo API clé
  • Votre application enregistrée dans Capgo (bunx @capgo/cli@latest app add si ce n'est pas le cas)
  • Configurez les informations d'identification de construction locales avec bunx @capgo/cli@latest build init Voir Gestion des informations d'identification pour la démonstration étape par étape du guide
  • Une construction locale réussie (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — la CI n'est pas le lieu pour déboguer votre première construction
  • La GitHub CLI (gh) installé et authentifié (gh auth login)

Configuration

Configuration

The Capgo CLI can export your local credentials as a ready-to-use .env La clé __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ peut exporter vos informations d'identification locales sous forme de fichier prêt à l'emploi. gh secret set -fCombiné avec

  1. Add your Capgo API key as a repository secret

    Ajoutez votre clé API __CAPGO_KEEP_1__ en tant que secret de dépôt

    La clé __CAPGO_KEEP_0__ n'est pas partie de la boutique de clés par application, ajoutez-la donc manuellement une fois :
    gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

    Copier dans le presse-papiers Générez la clé dans le tableau de bord Capgo avec télécharger ou des permissions supérieures.

  2. Exporter vos informations d'identification dans un .env fichier

    Exécutez le gestionnaire interactif d'informations d'identification :

    Fenêtre de terminal
    bunx @capgo/cli@latest build credentials manage --appId com.example.app

    Dans la TUI, sélectionnez Exporter vers .env. Le CLI écrit .env.capgo.<appId> à votre répertoire actuel avec des permissions 0600 (Propriétaire-lisible uniquement) — par exemple, .env.capgo.com.example.app. Lorsque les deux iOS et Android sont configurés, les secrets de tous les deux se trouvent dans le même fichier sous # === IOS === et # === ANDROID === les en-têtes de section. Les noms de variables d'environnement iOS et Android sont disjointes, ce qui signifie que les combiner ne crée pas de conflits.

  3. Push le .env fichier vers GitHub Secrets d'actions GitHub

    La gh secret set -f commande lit un fichier dotenv et crée un secret de repository par KEY=value ligne :

    Fenêtre de terminal
    gh secret set -f .env.capgo.com.example.app

    C'est tout — tous les secrets dont votre workflow a besoin sont maintenant dans GitHub. Vérifiez avec gh secret list.

  4. Créez le fichier de workflow

    Ajouter .github/workflows/capgo-build.yml à votre dépôt. Choisissez l'un des trois modèles de déclencheur ci-dessous en fonction de la façon dont vous souhaitez déclencher les builds.

Pour référence, gh secret set -f créera ces secrets de dépôt (votre fichier YAML de workflow les référence par ces noms exacts) :

PlateformeLes secrets créés
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
(ajoutés manuellement)CAPGO_TOKEN

Vous n'avez pas besoin de vous les rappeler — les exemples de workflow ci-dessous référencent déjà tous les éléments.

Les trois exemples ci-dessous couvrent les modèles les plus courants. Ils utilisent tous la même forme : récupérer le dépôt, installer les dépendances, construire les actifs web, synchroniser avec natif, puis appeler Capgo Build avec les variables d'environnement transmises.

Permet à n'importe qui avec accès en écriture de déclencher une construction depuis le Actions onglet dans GitHub avec un menu déroulant de plateforme. Utile pour des builds de test ad-hoc ou pour déclencher une mise à jour à la demande.

.github/flux de travail/capgo-build-manuel.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 }}

Remplacer com.example.app avec votre ID d'application. Une fois commit, allez à Actions → Capgo Build (manuel) → Exécuter le flux de travail pour le déclencher.

Les builds et les déploiements de toutes les plateformes sont effectués en parallèle chaque fois que vous poussez une étiquette de version comme v1.4.0Ceci est la configuration de production la plus courante — git tag v1.4.0 && git push --tags devient votre commande de mise en production.

github/flux de travail/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

La matrice exécute iOS et Android en parallèle sur des exécutants séparés. La mise à jour fail-fast: false signifie qu'une build iOS échouée ne supprimera pas la build Android en cours (et vice versa) — utile lorsque l'un des plateformes présente un problème de signature temporaire.

Capture les régressions de la mise en production native dès le début en produisant un débogage Android sur chaque mise à jour main. Chère à lancer, rapide feedback, et vous pouvez sauter l'upload sur la boutique Play pour le garder purement comme un test de fumée.

github/flux de travail/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

Le paths Le filtre s'assure que le flux de travail ne s'exécute pas sur les modifications uniquement documentaires. --no-playstore-upload Évite l'envoi sur la boutique Play (aucun PLAY_CONFIG_JSON nécessaire), et --output-upload produit une URL de téléchargement pour le fichier APK résultant afin que vous puissiez l'installer sur un appareil de test.

Éviter l'upload sur Google Play Store / TestFlight

Section intitulée “Éviter l'upload sur Google Play Store / TestFlight”

Pour les builds de test, évitez la soumission au magasin : Android utilise --no-playstore-upload; pour iOS, construisez en mode ad-hoc avec --ios-distribution ad_hoc (qui ne soumet jamais à l'App Store). Combinez-l’avec --output-upload pour obtenir une URL de téléchargement temporaire pour le fichier binaire.

Par défaut, les builds de mise en ligne chargent l'artifact signé et laissent l'action finale du magasin sous votre contrôle. Pour les releases CI qui devraient passer directement dans le flux d'examen du magasin, ajoutez --submit-to-store-review.

Android utilise votre PLAY_CONFIG_JSON compte de service. Sans une piste explicite, --submit-to-store-review se réfère par défaut à la piste de production avec release_status: completed. Préférez indiquer la piste au niveau de l'appel avec --android-track ou PLAY_STORE_TRACK, et surchargez le statut avec --android-release-status / PLAY_STORE_RELEASE_STATUS lorsque nécessaire :

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

Pour une version interne terminée au lieu de production :

- 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 utilise la clé de chemin d'accès API de App Store Connect et soumet la build TestFlight traitée à la revue de l'App Store. Il nécessite app_store la distribution ; --ios-testflight-groups est optionnel pour la distribution bêta externe et n'est pas requis pour la revue de l'App Store :

- 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

Lisez l'URL et le code QR de sortie de build et code

Section intitulée “Lisez l'URL et le code QR de sortie de build et code”

Passer --output-record <path> pour persister l'URL et le code QR de sortie de build et code sur le disque lorsque la build réussit, puis les lire à nouveau dans les étapes suivantes avec build last-outputAucune récupération de journal, aucune 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 écrit un enregistrement JSON (avec jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) et un code QR code à côté de /tmp/build.json.qr.png. build last-output les lit à nouveau :

  • --field outputUrl imprime uniquement l'URL de téléchargement (terminée par retour chariot ; sécurisée pour les) URL=$(...)).
  • --field qrCodePngPath imprime le chemin de la PNG afin que vous puissiez l'uploader en tant qu'annexe PR.
  • --qr imprime le code ASCII QR — insérez-l’à l'intérieur d'un code Markdown pour une scannabilité en ligne.

Omettre l'incrémentation du numéro de build

Sous-titre : Omettre l'incrémentation du numéro de build

Par défaut, chaque build de version augmente le numéro de build. Pour le fixer à une valeur que vous contrôlez (par exemple, la balise Git), passez --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 est déjà suffisamment rapide pour que le cache des dépendances JS ne rapporte rarement, mais les dépendances natives de Capacitor (CocoaPods, Gradle) sont dignes d'être mises en cache pour les projets plus importants :

- uses: actions/cache@v4
with:
path: |
~/.bun/install/cache
ios/App/Pods
android/.gradle
key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

Résolution des problèmes

Problème
Cause probableLe secret n'a pas été ajouté, ou le job n'a pas accès à celui-ci (vérifiez les protections d'environnement/branch)
CAPGO_TOKEN is not setErreurs de credenciaux iOS / Android manquants
n'a pas été exécuté, ou a été exécuté contre un répertoire différent. Vérifiez avecgh secret set -f Résolution des problèmes gh secret list
cap sync échoue dans CI mais fonctionne localementUn plugin natif n'est pas disponible package.jsonou vous avez oublié bun install avant cap sync
Avant de travailler sur une nouvelle fonctionnalité, créez un problème et discutez-en.Avant de travailler sur une nouvelle fonctionnalité, mentionnez le problème. bunx @capgo/cli@latest build credentials manage
La construction réussit mais l'application n'apparaît pas dans App Store ConnectL'ID d'équipe est incorrect ou l'enregistrement de l'application n'existe pas encore dans App Store Connect. Vérifiez localement avec node_modules La construction s'arrête après « Télédéchargement du projet »
Provisioning profile doesn't match bundle IDLe fichier d'archive du projet est inhabituellement volumineux — vérifiez que build init n'est pas chargé (ce n'est pas la norme par défaut) build credentials manage
Le fichier de provisionnement pointe vers un ID de bundle différent de celui que Xcode signe. Ré-exécutezN'oubliez pas de ré-exporter et de ré-pousser : bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId>
Le gestionnaire refuse d'écrire le fichier combinéLes clés de configuration partagées diffèrent entre plateformes — le gestionnaire avertit et demande confirmation. Confirmez pour écraser, ou ré-exportez par plateforme avec --platform ios / --platform android
build last-output imprime une URL videLa construction n'a pas réussi --output-uploadou elle a échoué avant de produire un artefact. outputUrl sera null dans l'enregistrement. Brancher sur [ -n "$URL" ] avant de l'utiliser
build last-output avec des erreurs Unsupported record schemaVersionLe runner est sur une version plus ancienne de CLI que celle qui a écrit l'enregistrement. Fixez la version explicite pour le producteur et le lecteur (par exemple bunx @capgo/cli@7.104.0 … sur les deux côtés) plutôt que @latest, qui flotte et peut dériver entre les tâches

Pour les échecs de construction spécifiques au plateforme, voir le Guide de dépannage.