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'ait besoin d'un Mac, d'Xcode ou d'Android Studio installés.

Ce que vous obtenez

Sorties sans intervention manuelle

Taguez une sortie dans Git et vos binaires signés iOS et Android 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 flux de travail. 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.

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)
• Configurez les informations d'identification de construction locales avec bunx @capgo/cli@latest build init — voir Gestion des informations d'identification pour la présentation é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
• 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 local d'informations d'identification (à partir de build init. Si vous n'avez pas encore configuré ces éléments, faites-le d'abord — le wizard gère 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

The Capgo CLI can export your local credentials as a ready-to-use .env Le __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 API __CAPGO_KEEP_1__ comme un secret de dépôt

   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échargement des permissions ou un niveau supérieur.

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

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

   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> dans votre répertoire actuel avec des permissions 0600 (seulement accessible au propriétaire) — 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, donc les combiner est sans conflit.

   Besoin d'un fichier par plateforme ?

   Passer --platform ios (ou --platform android) pour scoper le gestionnaire vers une plateforme. L'export produit ensuite un fichier par plateforme comme .env.capgo.com.example.app.iosClés de configuration partagées

   Utilisez (ou

   A quelques boutons de configuration (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) peuvent être stockés sous chaque plateforme indépendamment et peuvent s'être éloignés. Si le gestionnaire détecte un décalage, 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. Ré-exportez avec --platform si vous devez conserver des valeurs par plateforme.

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

   La 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 votre workflow a besoin sont maintenant dans GitHub. Vérifiez avec gh secret list.

   N'ajoutez pas le fichier .env à votre dépôt.

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

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

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

4. Créez le fichier de flux de travail

   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 votre section des secrets

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

Plateforme	Les 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é manuellement)	CAPGO_TOKEN

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

Exemples de workflow

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.

1. Déclencheur manuel

Permet à n'importe qui ayant 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 tests 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 2. Mise à jour sur Tag

Section intitulée « 2. Mise à jour sur Tag »

C'est la mise en production la plus courante — v1.4.02. Release on Tag 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 que si une mise en production iOS a échoué, elle ne supprimera pas la mise en production Android en cours (et vice versa) — utile lorsque l'un des plateformes a une question de signature transitoire.

Note

À propos du numéro de version : Capgo La mise en production auto-incrémente votre numéro de build à chaque mise en production. Si vous préférez le fixer sur la balise, voir Skip build number bumping ci-dessous.

3. Débogage Build sur Push vers Main

Capture les régressions de construction native dès le début en produisant une mise en production déboguée Android à chaque mise à jour sur main. Chère à lancer, rapide feedback, et vous pouvez ignorer la mise en ligne de la boutique Play pour qu'il s'agisse uniquement d'un 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 paths Le filtre s'assure que le flux de travail ne s'exécute pas sur les modifications uniquement documentaires. --no-playstore-upload ignore la soumission de 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.

Modèles courants

Ignorer l'upload de Google Play Store / TestFlight

Pour les builds de test, ignorer la soumission de l'application : 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’avec --output-upload pour obtenir une URL de téléchargement temporaire 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'artifact signé et laissent l'action finale de l'application sous votre contrôle. Pour les releases CI qui devraient passer directement dans le flux d'examen de l'application, ajoutez --submit-to-store-review.

Android utilise votre PLAY_CONFIG_JSON compte de service. Sans une piste explicite, --submit-to-store-review par défaut, il se conforme à la piste de production avec release_status: completed. Préférez indiquer la piste au moment 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 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

Attention

Cette voie ne soumet que l'artefact de construction. 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 de sortie de 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 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 à 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 de PR.
• --qr imprime le QR ASCII rendu — insérez-l’à l'intérieur d'un code Markdown pour une scannabilité en ligne.

Note

Le record n'est écrit que lors d'une build réussie. Les valeurs non prises en charge schemaVersion et inconnues --field sortent avec un code non nul, donc un CLI périmé dans le runner émet un avertissement bruyant au lieu d'émettre un URL vide en silence.

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

Par défaut, chaque build de release 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

Cache dépendances

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

Section intitulée « Résolution des problèmes »	Symptôme
CAPGO_TOKEN is not set	Cause probable
Le secret n'a pas été ajouté, ou le job n'a pas accès à celui-ci (vérifiez les protections d'environnement/branch)	gh secret set -f Erreurs de crédentials iOS / Android manquantes gh secret list
cap sync n'a pas été exécuté, ou a été exécuté contre un répertoire différent. Vérifiez avec : « fails in CI mais fonctionne localement »	Aucun plugin natif n'est disponible package.jsonou vous avez oublié bun install avant cap sync
Le build réussit mais aucune application n'apparaît dans App Store Connect	L'ID de l'équipe est incorrect ou l'enregistrement de l'application n'existe pas encore dans App Store Connect. Vérifiez localement avec bunx @capgo/cli@latest build credentials manage
Le build est bloqué après « Télédéchargement du projet »	Le fichier d'archive du projet est anormalement volumineux — 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. Ré-exécutez 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 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 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 avec des erreurs Unsupported record schemaVersion	Le 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

For les échecs de construction spécifiques à la plateforme, consultez le Guide de dépannage.

Étapes suivantes

Auto OTA ou Native Branchement CI entre mise à jour en direct et Capgo Build.

Déclencheur à partir de l'interface CI Exécution de Capgo Build depuis l'onglet Actions à la demande.

Webhooks de construction Démarrage du même flux de travail à partir d'un appel HTTP depuis un tableau de bord administrateur.

Paramètres des identifiants Référence complète pour la préparation des identifiants iOS et Android sous forme de secrets base64.

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