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

Lancements sans main

Taguez une version 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 sans Xcode, sans problèmes de provisioning et sans certificats de signature partagés en circulation.

Secrets scoping

Les identifiants se trouvent dans les secrets de votre GitHub repository, scoping à votre repo et visibles uniquement au workflow runner. Facile à mettre à jour, facile à auditer.

Constructions Parallèles

Constructions iOS et Android simultanément avec un travail de matrice. Une mise à jour typique se termine en moins de 10 minutes.

Prerequisites

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 pas
• Les informations de construction configurées localement avec bunx @capgo/cli@latest build init — voir Crédentials de gestion pour la procédure de l'assistant
• 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 crédentials existent déjà dans votre magasin de crédentials local (de build init). Si vous n'avez pas encore configuré, faites-le d'abord — l'assistant gère la création de certificats, les profils de provisionnement, les coffres-forts et les comptes de service Play Store de manière interactive.

Configuration

The Capgo CLI can export your local credentials as a ready-to-use .env Cela combiné avec gh secret set -fCela transforme l'ensemble de la configuration CI/CD en trois commandes — sans codage base64 manuel, sans manipulation de JSON, sans copie-collage de secrets.

1. Ajoutez votre Capgo API clé en tant que secret de repository

   La clé API n'est pas partie de l'entrepôt de crédentials par application, ajoutez-la donc manuellement une fois.

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

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

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

   Exécutez le gestionnaire de crédentials interactif :

   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 droits d'accès 0600 (seulement lisible par le propriétaire) — par exemple, .env.capgo.com.example.appLorsque 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 disjoint, donc les combiner est sans conflit.

   Besoin d'un fichier par plateforme ?

   Passer --platform ios (ou --platform android) pour restreindre le gestionnaire à une plateforme. L'exportation produit ensuite un fichier par plateforme comme .env.capgo.com.example.app.ios définir le gestionnaire sur une plateforme. L'export produit ensuite un fichier par plateforme comme

   Clés de configuration partagées

   Clés de configuration partagéesBUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) can be stored under each platform independently and may have drifted apart. If the manager finds drift, it prints the conflicting keys, asks for explicit confirmation before writing, and embeds the conflict list as a comment at the top of the file. Re-export with --platform Si vous devez 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 votre workflow a besoin sont maintenant dans GitHub. Vérifiez avec gh secret list.

   N'enregistrez pas le fichier .env

   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 à tout moment pour changer les informations d'identification — le fichier n'est pas un artefact à vie longue.

4. Créer le fichier de workflow

   Ajouter .github/workflows/capgo-build.yml Ajoutez-l’à votre dépôt. Sélectionnez l'un des trois modèles de déclencheur ci-dessous en fonction de la manière dont vous souhaitez déclencher les builds.

Ce qui se retrouve 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é manuellement)	CAPGO_TOKEN

Vous n'avez pas besoin de les retenir en tête — les exemples de workflow ci-dessous les référencent déjà tous.

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 Construire avec les informations d'identification passées en variables d'environnement.

1. Déclencheur manuel

Lets anyone with write access fire a build from the Actions Onglet 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.

/travaux/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 par votre ID d'application. Une fois commit, allez à Actions → Capgo Build (manuel) → 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/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. Configuration fail-fast: false une erreur de construction iOS n'annulera pas la construction Android en cours (et vice versa) — utile lorsque l'une des plateformes présente un problème de signature temporaire.

Note

À propos du numéro de version : Capgo Le numéro de build est automatiquement incrémenté à chaque build de version. Si vous préférez le fixer sur la balise, consultez Omettre l'incrémentation du numéro de build ci-dessous.

3. Débogage à la construction vers la branche principale

Captures les régressions de build natif tôt en produisant une build Android debug sur chaque push à mainÉconomique, rapide et vous pouvez sauter l'upload sur Google Play pour le garder purement comme 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 filter ensures the workflow doesn’t run on doc-only changes. --no-playstore-upload skippe la soumission sur Google Play Store (non) PLAY_CONFIG_JSON needed), 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.

Section intitulée « Modèles courants »

Skip Play Store / TestFlight upload

Pour les builds de test, sautez la soumission de 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.

Soumettre la mise à jour de l'application en revue

Par défaut, les builds de mise en ligne téléchargent l'artefact 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 defaults à 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 remplacer le statut par --android-release-status / PLAY_STORE_RELEASE_STATUS et surcharger le statut avec

- 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 un déploiement interne terminé 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 App Store Connect API et soumet la build TestFlight traitée à la revue de l'App Store. Il nécessite app_store 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

Caution

Cette voie ne soumet que l'artefact de construction. Les métadonnées de la liste de magasin, les groupes de testeurs, les détails de contact de la 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 de sortie de la construction et le QR code

Passer --output-record <path> Pour persister l'URL de l'artifact de build et le QR code sur le disque lorsque la build réussit, puis les lire à nouveau dans les étapes ultérieures. 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é par retour chariot ; sécurisé 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 — insérez-l’à l'intérieur d'un cadre Markdown code dans le commentaire de PR pour une lecture plus aisée.

Note

Le record n'est écrit que lors d'une build réussie. Non pris en charge schemaVersion et inconnu --field valeurs exit non-zero, donc un CLI périmé dans l'exécuteur fail bruyamment plutôt que d'émettre un URL vide en silence.

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

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

Note

Cette section traite de GitHub Actions la mise en cache sur l'exécuteur CI (local Pods/ et .gradle avant l'upload). Capgo garde également un avant l'upload). __CAPGO_KEEP_0__ conserve également une par application sur l'exécuteur de build (activé par défaut; omettre) cache_key pour le cache partagé général). Passer --cache-key pour la mise en cache générale partagée). Passer --no-cache à la partition RC et production, ou Dépannage : restauration de cache incorrecte.

bun install Il 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') }}

Troubleshooting

Symptôme	Cause probable
CAPGO_TOKEN is not set	Le secret n'a pas été ajouté ou le job n'y a pas accès (vérifiez les protections d'environnement/branche).
Erreurs de credenciaux iOS / Android manquants	gh secret set -f was pas exécuté, ou a été exécuté sur un dépôt différent. Vérifiez avec gh secret list
cap sync échoue dans CI mais fonctionne localement	Un plugin natif n'est pas disponible package.json, ou vous avez oublié bun install avant cap sync
Créez un problème et discutez avant de travailler sur une nouvelle fonctionnalité	L'ID d'é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
La construction s'arrête après « Chargement du projet »	Projet d'archive est anormalement volumineux — vérifiez que node_modules La construction s'arrête après « Télédéchargement du projet »
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 n'est pas téléchargé (ce n'est pas la norme par défaut) build credentials manage
Les identifiants ont changé localement mais l'erreur persiste en CI.	pour mettre à jour le profil, puis ré-exportez avec 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. Confirmer pour écraser, ou ré-exporter 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 Unsupported record schemaVersion	The runner is on an older CLI than the one that wrote the record. Pin both producer and reader to the same explicit version (e.g. bunx @capgo/cli@7.104.0 … Les deux côtés) plutôt que @latestsur les deux côtés) plutôt que

qui flotte et peut dériver entre les tâches Guide de dépannage.

Étapes suivantes

Section intitulée « Étapes suivantes » Branch CI entre live update téléchargement et Capgo Build.

Branchement CI entre l'upload __CAPGO_KEEP_0__ et la Build __CAPGO_KEEP_1__ Run Capgo Construire à partir de la vue Actions à la demande.

Créez des Webhooks Start the same workflow from an admin dashboard HTTP call.

Paramètres de connexion 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 drapeaux et variables d'environnement pour affiner vos builds.