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

Lancements sans main

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

Aucune configuration locale

Les contributeurs sous Windows ou Linux peuvent déclencher les builds iOS. Aucun Xcode, aucun problème de provisionnement, aucune certificat de signature partagé flottant sur les ordinateurs portables.

Secrets scoping

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

Lancements parallèles

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

Prérequis

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

• Un compte Capgo avec une abonnement actif et un Capgo API clé
• Votre application enregistrée sur Capgo (bunx @capgo/cli@latest app add si ce n'est pas le cas)
• Les informations de build configurées localement avec bunx @capgo/cli@latest build init — voir Gestion des informations de connexion pour la walkthrough du guide
• Une build locale réussie (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug — Le CI n'est pas le lieu pour déboguer votre première build
• Le GitHub CLI (gh) installés et authentifiés (gh auth login)

Note

La procédure suivante suppose que les informations d'identification existent déjà dans votre magasin de crédentiels local (à partir de build init). Si vous n'avez pas configuré encore, faites-le d'abord — le guide vous accompagne pour la création de certificats, les profils de provisionnement, les clés de coffre 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 fichier. Associé à gh secret set -fCette opération simplifie 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.

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

   La clé API n'est pas partie de la boutique 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 tableau de bord Capgo avec l'envoi permissions ou supérieures. Exporter vos informations d'identification dans un

2. fichier .env Export your credentials to a __CAPGO_KEEP_0__ file

   Exécutez le gestionnaire interactif de mots de passe :

   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 (seulement lisible par le propriétaire) — par exemple, .env.capgo.com.example.appDès que 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 en-têtes de section. Les noms des variables d'environnement iOS et Android sont disjointes, ce qui signifie qu'en les combinant, il n'y a pas de conflit.

   Besoin d'un fichier par plateforme?

   Passer --platform ios (ou --platform android) pour scoper le gestionnaire à 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. Ré-exportez avec --platform si vous avez besoin de conserver des valeurs par plateforme.

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

   Le gh secret set -f 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 en texte clair. 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 .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.

Quels éléments se retrouvent dans vos secrets

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

Plateforme	Secrets créés
IOS	BUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
Android	ANDROID_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 les retenir en mémoire — les exemples de workflow ci-dessous référencent déjà tous les éléments.

Exemples de workflow

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, créez les actifs web, synchronisez avec le natif, puis appelez Capgo Build avec les variables d'environnement transmises.

1. Déclencheur manuel

Permet à tout utilisateur disposant d'accès en écriture de déclencher une construction depuis le Actions menu déroulant de la plateforme dans GitHub avec un menu déroulant de la plateforme. Utile pour les tests ad-hoc ou pour lancer une mise à jour à la demande.

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

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

2. Lancer sur Tag

Construit et expédie les deux 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 qu'une erreur de construction iOS ne supprimera pas la construction Android en cours (et vice versa) — utile lorsque l'une des plateformes a une question de signature transitoire.

Note

A propos du numéro de version : Capgo Le numéro de build auto-incrémente automatiquement votre numéro de build à chaque build de version. Si vous préférez le fixer sur la balise, voir Passer à l'étape suivante ci-dessous.

3. Lancer un build de débogage lors d'une mise à jour de la branche principale

Permet de détecter les régressions de build natives dès le début en produisant un build de débogage Android à chaque mise à jour de main. C'est peu coûteux, vous obtenez des retours rapides, et vous pouvez ignorer l'upload vers la Play Store pour le garder purement comme test de fumée.

.github/travaux/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 filtre s'assure que le flux de travail ne s'exécute pas sur les modifications uniquement documentaires. paths sauter la soumission de la boutique Play (pas --no-playstore-upload nécessaire), et PLAY_CONFIG_JSON produit une URL de téléchargement pour le fichier APK résultant afin que vous puissiez l'installer sur un appareil de test. --output-upload Modèles courants

Section intitulée “Modèles courants”

Section intitulée “Sauter la soumission de la boutique Play / TestFlight”

; pour iOS, construire en mode ad-hoc avec --no-playstore-upload(qui ne soumet jamais à l'App Store). Combinez les deux avec --ios-distribution ad_hoc Common Patterns --output-upload pour obtenir une URL de téléchargement temporairement disponible pour le binaire.

Lisez l'URL de sortie de la construction et le QR code

Passer --output-record <path> pour persister l'URL de l'artefact de construction et le QR code sur le disque lorsque la construction réussit, puis les lire à nouveau dans les étapes ultérieures avec build last-outputAucune récupération de journaux, 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 PNG 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 URL=$(...)).
• --field qrCodePngPath imprime le chemin du PNG afin que vous puissiez le télécharger en tant qu'attache de PR.
• --qr imprime l'ASCII QR rendu — glissez-le à l'intérieur d'un code de Markdown sur le commentaire de la PR pour une scannabilité inline.

Note

Le record n'est écrit que lors d'une build réussie. Non pris en charge schemaVersion et inconnu --field valeurs quittent le processus avec un code non nul, donc un CLI périmé dans l'exécuteur émet un URL vide à voix haute au lieu d'émettre silencieusement.

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

Mettre en cache les dépendances

bun install est déjà suffisamment rapide pour que le cache de dépendances JS ne se justifie 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 credenciaux iOS / Android manquants	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 dans package.json, ou vous avez oublié bun install avant cap sync
La construction réussit mais aucune application n'apparaît dans App Store Connect	ID d'équipe incorrect, ou le record d'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 »	L'archive du projet est inhabituellement grande — 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	Le plan de provisionnement pointe vers un ID de bundle différent de celui que Xcode signe. Re-run build init pour rafraîchir le profil, puis ré-export avec build credentials manage
Les informations d'identification ont changé localement mais CI échoue toujours	Ne vous 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-une-gagne, 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 au dossier. Brancher sur [ -n "$URL" ] avant de l'utiliser
build last-output avec des erreurs Unsupported record schemaVersion	Le constructeur est sur une version plus ancienne de CLI que celle qui a écrit le dossier. Fixer la même version explicite (par exemple bunx @capgo/cli@7.104.0 … sur les deux côtés) plutôt que @latestqui flotte et peut dériver entre les tâches

Pour les échecs de construction spécifiques au plateforme, voir 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 sur 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.