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, balise ou déclencheur manuel peut produire des applications signées et prêtes à l'entrepôt — 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 version dans Git et vos binaires iOS et Android signés sont soumis automatiquement à TestFlight et à la Play Store.

Pas de configuration locale

Les contributeurs sous 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 d'identification vivent dans les secrets de GitHub du référentiel, étendus à votre référentiel et visibles uniquement pour l'exécuteur de flux de travail.

Constructions Parallèles

Construirez iOS et Android en même temps avec un job 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 souscription active et un Capgo API clé
• Votre application enregistrée dans Capgo (bunx @capgo/cli@latest app add si ce n'est pas le cas)
• Les informations de construction configurées localement avec bunx @capgo/cli@latest build init — voir Gestion des Identifiants pour la procédure guidée du sorcier
• 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
• Le GitHub CLI (gh) installé et authentifié (gh auth login)

Remarque

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

Configuration

Le Capgo CLI peut exporter vos informations d'identification locales sous forme de fichier prêt à l'emploi. .env Lorsqu'il est combiné avec gh secret set -f, cela 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 Capgo API clé en tant que secret de dépôt

   La clé API n'est pas partie de l'ensemble des informations d'identification 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 ou un niveau de permission supérieur.

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

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

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

   Dans l'interface TUI, sélectionnez Exporter vers .env. Le CLI écrit .env.capgo.<appId> dans votre répertoire actuel avec des droits 0600 (lecture par le propriétaire uniquement) — par exemple, .env.capgo.com.example.app. Lorsque les deux iOS et Android sont configurés, les secrets des deux plateformes se retrouvent dans le même fichier sous la racine # === IOS === et les en-têtes de section. Les noms de variables d'environnement iOS et Android sont disjointes, donc la combinaison d'elles est sans conflit. # === ANDROID === Besoin d'un fichier par plateforme ?

   Passer

   (ou --platform ios ) pour scoper le gestionnaire à une plateforme. L'export produit ensuite un fichier par plateforme comme --platform androidUtile lorsque les secrets iOS et Android vivent dans des dépôts ou des environnements différents. .env.capgo.com.example.app.iosClés de configuration partagées

   Un certain nombre de paramètres de configuration (

   ) peuvent être stockés sous chaque plateforme indépendamment et peuvent s'être éloignés. Si le gestionnaire détecte un dérive, il imprime 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 avecBUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTIONRe-export with --platform If vous avez besoin de conserver des valeurs par plateforme.

3. Envoyez le fichier à __CAPGO_KEEP_0__ Secrets d'actions .env file to GitHub Actions secrets

   commande lit un fichier dotenv et crée un secret de repository par gh secret set -f Ligne : KEY=value Fenêtre de terminal

   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.

   Elle contient des matériaux de signature en texte clair. Une fois que vous l'avez envoyé à __CAPGO_KEEP_0__:

   Push the file to GitHub Actions secrets

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

   Ré-exportez à tout moment lorsque vous devez faire pivoter les informations d'identification — le fichier n'est pas un artefact à long terme.

4. Créer 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.

Ce qui se retrouve dans vos secrets

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

Secrets créés	Section titled “Ce qui se retrouve dans vos secrets”
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
(added manuellement)	CAPGO_TOKEN

Vous n'avez pas besoin de vous souvenir de ces éléments — 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 référentiel, installez les dépendances, construisez les actifs web, synchronisez avec le natif, puis appelez Capgo Build avec les variables d'environnement transmises pour les informations d'identification.

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 plateforme dans GitHub . Utile pour les tests ad-hoc ou la mise en route d'une mise à jour sur demande.

/travaux/github-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 par votre ID d'application. Une fois commit, allez à Actions → Capgo Construction (Manuelle) → Exécuter 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.

/travaux/github-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 en place fail-fast: false signifie un build iOS échoué ne sera pas annulé par le build Android en cours (et vice versa) — utile lorsque l'une des plateformes a un problème de signature transitoire.

Remarque

À propos du numéro de version : Capgo Build augmente automatiquement 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 en dessous.

3. Build de débogage sur Push vers Main

Captures les régressions de build natif tôt en produisant un build de débogage Android à chaque push vers main. Chère en fonctionnement, rapide feedback, et vous pouvez sauter l'upload de la boutique Play pour garder cela purement 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 sauter l'upload de la boutique Play (pas 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 l'upload de la boutique Play / TestFlight

Pour les builds de test, sautez la soumission de l'application : 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-le avec --output-upload pour obtenir une URL de téléchargement temporaire du fichier binaire.

Soumettez la version de l'application pour examen

Par défaut, les builds de version publique 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 le flux d'examen de l'application, ajoutez --submit-to-store-review.

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

- 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 utilise la clé de chemin App Store Connect API et soumet la build TestFlight traitée à la revue de l'App Store. Cela 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

Attention

Cette voie ne soumet que l'artifact de build. Les métadonnées de la liste de magasin, 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écutent.

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

Passer --output-record <path> to persist the build artifact URL and QR code to disk when the build succeeds, then read it back in subsequent steps with build last-output. Aucune 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 PNG QR code en parallèle à /tmp/build.json.qr.png. build last-output le lit à nouveau :

• --field outputUrl imprime uniquement l'URL de téléchargement (terminée par retour chariot ; sécurisé pour URL=$(...)).
• --field qrCodePngPath imprime le chemin du PNG afin que vous puissiez le télécharger comme une pièce jointe de PR.
• --qr imprime le QR ASCII rendu — insérez-le à l'intérieur d'un cadre Markdown code dans le commentaire de PR pour une scannabilité en ligne.

Remarque

L'enregistrement n'est écrit que lors d'une construction réussie. Non pris en charge schemaVersion et inconnu --field les valeurs sortent avec un code d'erreur, donc un CLI périmé dans l'exécuteur échoue bruyamment au lieu d'émettre silencieusement une URL vide.

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 C'est déjà suffisamment rapide pour que le cache des dépendances JS ne soit rarement rentable, 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)
Les erreurs de mot de passe iOS / Android manquants	gh secret set -f n'a pas été exécuté, ou a été exécuté contre un référentiel 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	L'ID d'équipe est incorrect, ou le record de l'application n'existe pas encore dans App Store Connect. Vérifiez localement avec bunx @capgo/cli@latest build credentials manage
La construction est bloquée après « Télédéchargement du projet »	L'archive du projet est anormalement grande — vérifiez que node_modules n'est pas téléchargé (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-exécutez build init pour rafraîchir le profil, puis ré-exportez avec build credentials manage
Les informations d'identification ont changé localement mais la CI continue de ne pas fonctionner	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 configuration partagées diffèrent entre plateformes — le gestionnaire avertit et demande confirmation. Confirmez pour écraser l'un des deux, 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 l'enregistrement. Brancher sur [ -n "$URL" ] avant de l'utiliser
build last-output erreurs avec Unsupported record schemaVersion	Le runner est sur une version plus ancienne de CLI que celle qui a écrit l'enregistrement. Fixez la version explicite du producteur et du lecteur sur la même version (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 à la 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 sous forme de secrets base64.

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

Constructions Android Configuration de clé de stockage, comptes de service Google Play et gestion de saveurs.

Options de configuration Tous les drapeaux CLI et variables d'environnement pour affiner vos constructions.