GitHub Actions

Copiez un prompt de configuration avec les étapes d'installation et la guide markdown complet pour ce plugin.

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 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 des builds iOS. Pas de 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 répertoire GitHub, scoping à votre répertoire et visible uniquement pour l'exécuteur de workflow. Facile à mettre à jour, facile à auditor.

Builds 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

Un compte __CAPGO_KEEP_0__ avec une souscription active et un

Capgo __CAPGO_KEEP_1__ clé Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add If pas)
Configurez les informations d'identification de construction locales avec bunx @capgo/cli@latest build init — voir Gestion des informations d'identification pour la démonstration étape par étape du guide
Une construction 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 construction
Le GitHub CLI (gh) installé et authentifié (gh auth login)

Configuration

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

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

La API clé n'est pas partie de la base de données d'informations d'identification par application, ajoutez-la donc manuellement :
Fenêtre de terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Générez la clé dans le tableau de bord Capgo avec l'upload des permissions ou supérieures.
Exporter vos identifiants dans un .env fichier

Exécutez le gestionnaire interactif des identifiants :
Fenêtre de terminal
```
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> ajoutez-le à votre répertoire actuel avec des permissions 0600 (lecture par le propriétaire uniquement) — par exemple, .env.capgo.com.example.appQuand 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 titres de section. Les noms des variables d'environnement iOS et Android sont disjointes, ce qui signifie que les combiner n'est pas conflictuel.

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

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 un dérive, il affiche les clés en conflit, demande une confirmation explicite avant d'écrire et insère la liste des conflits en tant que commentaire en haut du fichier. Re-export avec --platform si vous avez besoin de conserver des valeurs par plateforme.
Envoi du .env fichier vers les secrets Actions de GitHub

La gh secret set -f commande lit un fichier dotenv et crée un secret de repository par KEY=value ligne :
Fenêtre de terminal
```
gh secret set -f .env.capgo.com.example.app
```
C'est tout — chaque secret dont votre workflow a besoin est maintenant dans GitHub. Vérifiez avec gh secret list.
N'envoyez pas le fichier .env
Il contient des matériaux de signature texte. Une fois que vous l'avez poussé sur GitHub:
Fenêtre de terminal
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Réexportez à tout moment si vous devez faire pivoter les informations d'identification — le fichier n'est pas un artefact à long terme.
Créez 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

Pour référence, gh secret set -f créera ces secrets de dépôt (vos fichiers YAML de workflow les référencent 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 vous souvenir de ces derniers — 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 : 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

Tout utilisateur disposant d'une écriture peut lancer une construction à partir de l' Actions rubrique dans GitHub avec un menu déroulant de plateforme. Utile pour les tests ad-hoc ou la mise en route d'une mise à jour sur demande.

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 dans Actions → Capgo Construction (Manuelle) → Exécuter le flux de travail pour le déclencher.

2. Mise à jour sur Tag

Les constructions et les expéditions de toutes les plateformes en parallèle chaque fois que vous poussez une étiquette de version comme v1.4.0. Cette est la configuration de production la plus courante — git tag v1.4.0 && git push --tags devient votre commande de mise en production.

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 à fail-fast: false signifie que la construction iOS échouée ne supprimera pas la construction Android en cours (et vice versa) — utile lorsque l'un des plateformes a une question de signature transitoire.

3. Débogage de la construction sur la mise à jour de la branche principale

Captures les régressions de construction native en produisant un débogage Android sur chaque mise à jour de mainFonctionne à bas coût, offre un feedback rapide et vous pouvez ignorer la mise en ligne sur Play Store pour le garder purement comme un test de fumée.

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 Saut la soumission sur Play Store (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

filter ensures the workflow doesn’t run on doc-only changes.

Sauter l'upload sur Google Play / TestFlight

Pour les builds de test, sauter 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 les deux avec --output-upload pour obtenir une URL de téléchargement temporaire du fichier 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 analyse de logs, 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 cela /tmp/build.json.qr.png. build last-output lit-le à 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 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é inline.

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, l'étiquette 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 clés iOS / Android manquantes	`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 enregistrement d'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 « Envoi du projet »	L'archive du projet est inhabituellement 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-run `build init` pour rafraîchir le profil, puis ré-export avec `build credentials manage`
Les identifiants ont changé localement mais CI échoue toujours	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-upload`ou 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 le record. Fixez la version explicite pour le producteur et le 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 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 sous forme de secrets base64.

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

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

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