GitHub Actions

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.

Ce que vous obtenez

Taguez 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 les builds iOS. Pas d'Xcode, pas de problèmes de provisionnement, pas de certificats de signature partagés qui flottent sur les ordinateurs portables.

Secrets scoping

Les informations de connexion vivent dans les secrets de __CAPGO_KEEP_0__ repository, scoping à votre repository et visible uniquement par le déclencheur de workflow. Facile à mettre à jour, facile à auditor.

Credentials live in GitHub repository secrets, scoped to your repo and visible only to the workflow runner. Easy to rotate, easy to audit.

Construirez iOS et Android en même temps avec un job de matrice. Une sortie typique se termine en moins de 10 minutes.

Prérequis

Prérequis

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

• Un compte Capgo avec une souscription active et une clé __CAPGO_KEEP_1__ Capgo API key
• Your app registered in Capgo (bunx @capgo/cli@latest app add Les informations de build configurées localement avec — voir
• Gestion des informations de build bunx @capgo/cli@latest build init pour la procédure guidée du wizard Une build locale réussie ( )
• Un build local réussi (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — le CI n'est pas l'endroit pour déboguer votre première build
• Le GitHub CLI (gh) installé et authentifié (gh auth login)

Note

Le flux ci-dessous suppose que les informations d'identification existent déjà dans votre magasin de fichiers de connexion local (à partir de build init). Si vous n'avez pas encore configuré, faites-le d'abord — le guide gère la création de certificats, les profils de provisionnement, les coffres de clés et les comptes de service Google Play de manière interactive.

Configuration

Le Capgo CLI peut exporter vos informations d'identification locales sous forme de fichier prêt à l'emploi. .env Cela combiné avec gh secret set -f, transforme l'ensemble de la configuration CI/CD en trois commandes — pas de codage base64 manuel, pas de manipulation de JSON, pas de copie-collage de secrets par secret.

1. Ajoutez votre clé Capgo API en tant que secret de dépôt

   La clé API n'est pas partie de l'ensemble de crédentials par application, ajoutez-la donc manuellement :

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   Générez la clé dans le Capgo tableau de bord avec l'envoi permissions ou supérieures.

2. Exporter vos crédentials dans un .env fichier

   Exécutez le gestionnaire interactif de crédentials :

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

   Dans l'interface TUI, sélectionnez Exporter vers .envLe CLI écrit .env.capgo.<appId> dans votre répertoire actuel avec les droits 0600 Par exemple, .env.capgo.com.example.appLorsque les deux iOS et Android sont configurés, les secrets de tous les deux plateformes se retrouvent dans le même fichier sous # === IOS === et # === ANDROID === Les noms des variables d'environnement iOS et Android sont disjointes, ce qui signifie que les combiner ne pose pas de problème.

   Avez-vous besoin d'un fichier par plateforme ?

   Passer --platform ios (ou --platform android) pour définir le gestionnaire sur une plateforme. L'export produit ensuite un fichier par plateforme comme .env.capgo.com.example.app.iosPratique lorsque les secrets iOS et Android vivent dans des dépôts ou des environnements différents.

   Clés de configuration partagées

   Un certain nombre de paramètres de configuration (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) peuvent être stockés indépendamment sous chaque plateforme et peuvent s'être éloignés. Si le gestionnaire détecte des différences, il affiche les clés en conflit, demande une confirmation explicite avant d'écrire et insère la liste des conflits sous forme de commentaire en haut du fichier. Re-export avec --platform si vous avez besoin de conserver les valeurs par plateforme.

3. Pusher le .env fichier vers GitHub Secrets d'actions de Capgo

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

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

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

   N'oubliez pas de ne pas commiter le fichier .env

   Il contient des matériaux de signature texte. Une fois que vous l'avez poussé vers GitHub:

   echo '.env.capgo.*' >> .gitignore
   rm .env.capgo.*

   Ré-exportez à tout moment si vous devez faire tourner les crédits — le fichier n'est pas un artefact à long terme.

4. Créez le fichier de workflow

   Ajoutez-le à 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. .github/workflows/capgo-build.yml Quels éléments se retrouvent dans vos secrets ?

Pour référence,

Plateforme gh secret set -f Secrets créés

iOS	Android
(ajoutés manuellement)	BUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
Vous n'avez pas besoin de les retenir en mémoire — les exemples de workflow ci-dessous référencent déjà tous les éléments.	ANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON
Ajoutez-le à 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.	CAPGO_TOKEN

Quels éléments se retrouvent dans vos secrets ?

Exemples de flux de travail

Les trois exemples ci-dessous couvrent les modèles les plus courants. Ils utilisent tous la même forme : consultez le dépôt, installez les dépendances, construisez les actifs web, synchronisez avec le natif, puis appelez Capgo Build avec les variables d'environnement transmises.

1. Déclencheur manuel

Permet à n'importe qui ayant accès en écriture de déclencher une construction à partir de l' Actions onglet dans GitHub avec un menu déroulant de plateforme. Utile pour les tests ad-hoc ou pour lancer une mise à jour à la demande.

github/workflows/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 par votre ID d'application. Une fois commit, allez à Actions → Capgo Build (manuel) → Exécutez le flux de travail pour le déclencher.

2. Lancer sur Tag

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

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

La matrice exécute iOS et Android en parallèle sur des exécutants séparés. Définir fail-fast: false signifie que si une build iOS échoue, elle ne sera pas annulée et l'exécution en cours d'Android ne sera pas interrompue (et vice versa) — utile lorsque l'une des plateformes a un problème de signature temporaire.

Note

À propos du numéro de version : Capgo Le numéro de build auto-incrémente votre numéro de build à chaque build de publication. Si vous préférez le fixer sur la balise, voir Ignorer l'incrémentation du numéro de build ci-dessous.

3. Build de débogage sur Push vers Main

Captures les régressions de build natif tôt en produisant un build Android de débogage à chaque push vers mainBon marché à lancer, rapide feedback, et vous pouvez ignorer l'upload sur Play Store pour le garder purement comme test de fumée.

. 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

Le paths filter s'assure que le flux de travail ne s'exécute pas sur les modifications uniquement de documentation. --no-playstore-upload sauter la soumission de la boutique Play (non 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.

Modèles courants

Sauter la soumission de la boutique Play / TestFlight

Pour les builds de test, sauter la soumission de la boutique : Android utilise --no-playstore-upload; pour iOS, construire en mode ad-hoc avec --ios-distribution ad_hoc (qui ne soumet jamais à l'App Store). Combinez l'un ou l'autre avec --output-upload pour obtenir une URL de téléchargement temporairement valable pour le fichier binaire.

Soumettre la mise à jour de l'application pour examen

Par défaut, les builds de mise à jour téléchargent l'artefact signé et laissent l'action finale de l'application sous votre contrôle. Pour les releases CI qui devraient se déplacer directement dans la flux d'examen de l'application, ajoutez --submit-to-store-review.

Android utilise votre PLAY_CONFIG_JSON compte de service et soumet la mise à jour de Google Play au lieu de la laisser inactive. Ajoutez --store-release-name, --store-release-notes, et des entrées optionnelles lorsque vous voulez que la mise à jour de Play porte le même tag et les notes de changement localisées que CI : --store-release-notes-locale Copier dans le presse-papier

- 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 uses the App Store Connect API key path and submits the processed TestFlight build to App Store review. It requires app_store est optionnel pour la distribution bêta externe et n'est pas requis pour l'examen de l'App Store : --ios-testflight-groups Copier dans le presse-papier

- 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

Attention

Cette chemin ne soumet que l'artefact de build. Les métadonnées de la liste d'applications, les groupes de testeurs, les détails de contact de revue, les réponses de conformité et les choix de déploiement doivent encore être prêts dans App Store Connect ou Google Play Console avant que les CI les exécute.

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 ultérieures 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 PNG code aux côtés 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 URL=$(...)).
• --field qrCodePngPath imprime le chemin de la PNG afin que vous puissiez l'uploader comme pièce jointe d'un PR.
• --qr imprime l'ASCII QR rendu — insérez-le à l'intérieur d'un cadre Markdown code dans la commentaires du PR pour la scannabilité inline.

Note

Le record n'est écrit que lors d'une construction réussie. Non pris en charge schemaVersion et inconnus --field les valeurs sortent avec un code d'erreur non nul, donc un CLI obsolète dans l'exécuteur émet un message d'erreur bruyant au lieu d'émettre un URL vide en silence.

Ignorer 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

Dépendances de cache

bun install est déjà suffisamment rapide pour que le cache de 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

Symptôme	Cause probable
CAPGO_TOKEN is not set	Le secret n'a pas été ajouté, ou le job n'a pas accès à celui-ci (vérifiez les protections d'environnement/branch)
Erreurs de crédentials iOS / Android manquantes	gh secret set -f n'a pas été exécuté, ou a été exécuté contre un dépôt différent. Vérifiez avec gh secret list
cap sync échoue en CI mais fonctionne localement	Un plugin natif n'est pas disponible package.jsonou vous avez oublié bun install avant cap sync
La construction réussit mais aucune application n'apparaît dans App Store Connect	L'ID de l'équipe est incorrect, ou le dossier de l'application n'existe pas encore dans App Store Connect. Vérifiez localement avec bunx @capgo/cli@latest build credentials manage
La construction s'arrête après « Envoi du projet »	Le fichier d'archive du projet est anormalement volumineux — vérifiez que node_modules n'est pas envoyé (ce n'est pas la norme par défaut)
Provisioning profile doesn't match bundle ID	La carte de provisionnement pointe vers un ID de bundle différent de celui que Xcode signe. Re-run build init pour mettre à jour le profil, puis ré-exportez avec build credentials manage
Les identifiants ont changé localement mais la CI échoue encore	N'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 la configuration partagée diffèrent entre les 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 vide	La construction n'a pas réussi --output-uploadou elle a échoué avant de produire un artefact. outputUrl sera null dans le registre. Brancher sur [ -n "$URL" ] avant de l'utiliser
build last-output échoue avec Unsupported record schemaVersion	Le runner est sur une version plus ancienne de CLI que celle qui a écrit le registre. 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 erreurs de construction spécifiques à la plateforme, consultez le Guide de dépannage.

Étapes suivantes

Configuration des identifiants Référence complète pour la préparation des identifiants iOS et Android en tant que secrets base64.

Constructions iOS Guide plus approfondi sur les certificats, les profils et la soumission de l'App Store.

Constructions Android Configuration de la clé de stockage, des comptes de service Play Store et gestion des saveurs.

Options de configuration Toutes les CLI options et variables d'environnement pour affiner vos constructions.