GitHub Azioni

Automatizza le tue compilazioni iOS e Android direttamente dal tuo repository GitHub. Con un unico file di workflow e un pugno di segreti del repository, ogni push, etichetta o trigger manuale può produrre app firmate e pronte per il magazzino — senza che nessun membro della squadra abbia bisogno di un Mac, Xcode o Android Studio installato.

Cosa Otterrai

Rilasci senza Intervento

Etichetta un rilascio in Git e i tuoi binari iOS e Android firmati vengono inviati automaticamente a TestFlight e Play Store.

Nessuna Configurazione Locale

Contributori su Windows o Linux possono attivare le build per iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira sui laptop.

Segreti Scoperti

I credenziali vivono nei segreti del repository GitHub, scritti per il tuo repository e visibili solo al runner del workflow. Facile da rotare, facile da auditare.

Costruzioni in Parallelo

Costruisci iOS e Android allo stesso tempo con un lavoro di matrice. Un rilascio tipico si conclude in meno di 10 minuti.

Prerequisites

Prima di configurare il workflow, assicurati di avere:

• Un account Capgo con una sottoscrizione attiva e un Capgo API chiave
• La tua app registrata in Capgo (bunx @capgo/cli@latest app add se non)
• Le credenziali di costruzione configurate localmente con bunx @capgo/cli@latest build init — vedi Gestione delle credenziali per la guida passo passo del wizard
• Un costruzione locale riuscita (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — il CI non è il luogo per debuggare la tua prima build
• The GitHub CLI (gh) installato e autenticato (gh auth login)

Nota

Di seguito si assume che le credenziali siano già presenti nel tuo archivio delle credenziali locale (da) build initSe non le hai ancora configurate, fai prima — il wizard gestisce la creazione del certificato, le profili di provisioning, le chiavi di archiviazione e gli account del servizio Play Store in modo interattivo.

Setup

Il Capgo CLI può esportare le tue credenziali locali come un file pronto all'uso .env file. Combinato con gh secret set -fQuesto converte l'intera configurazione CI/CD in tre comandi — nessuna codifica base64 manuale, nessuna gestione JSON, nessun copia-incolla-segreti-segreti-segreti.

1. Aggiungi la tua chiave Capgo API come segreto del repository

   La chiave API non fa parte del repository di credenziali per app, quindi aggiungila manualmente una volta sola.

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   Genera la chiave nel Capgo dashboard con caricamento o un livello di autorizzazione superiore.

2. Esporta le tue credenziali in un .env file

   Esegui il gestore delle credenziali interattivo:

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

   Nella TUI, seleziona Esporta in .env. Il CLI scrive .env.capgo.<appId> nel tuo directory corrente con modalità 0600 (solo lettura del proprietario) — ad esempio, .env.capgo.com.example.app. Quando sono configurati sia iOS che Android, i segreti di entrambe le piattaforme finiscono nel medesimo file sotto # === IOS === e # === ANDROID === section headers. iOS and Android env-var names are disjoint, so combining them is conflict-free.

   Hai bisogno di un file per piattaforma?

   Pass --platform ios Passa --platform android) per limitare il manager a una piattaforma. L'esportazione produce quindi un file per piattaforma. .env.capgo.com.example.app.iosUtile quando i segreti iOS e Android vivono in repository o ambienti diversi.

   Chiavi di configurazione condivise

   Una manciata di interruttori di configurazione (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) possono essere memorizzati indipendentemente per ogni piattaforma e possono essere diventati diversi. Se il manager trova una divergenza, stampa le chiavi in conflitto, chiede una conferma esplicita prima di scrivere e inserisce la lista dei conflitti come commento in cima al file. Ri-esporta con --platform se hai bisogno di preservare i valori per piattaforma.

3. Spingi il .env file a GitHub Segreti Actions

   La gh secret set -f comanda legge un file dotenv e crea un segreto repository per KEY=value linea:

   gh secret set -f .env.capgo.com.example.app

   Ecco tutto — ogni segreto che il tuo workflow richiede è ora in GitHub. Verifica con gh secret list.

   Non commettere il file .env

   Contiene materiale di firma in testo piano. Una volta che hai spinto su GitHub:

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

   Rieporta ogni volta che è necessario rotare le credenziali — il file non è un artefatto a lunga durata.

4. Crea il file di workflow

   Aggiungi .github/workflows/capgo-build.yml aggiungi il tuo repository. Scegli uno dei tre modelli di trigger riportati di seguito in base a come desideri avviare le costruzioni.

Cosa finisce nei tuoi segreti

Per riferimento, gh secret set -f creerà questi segreti del repository (il tuo file YAML di workflow li riferisce con questi nomi esatti):

Piattaforma	Segreti creati
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
(aggiunti manualmente)	CAPGO_TOKEN

Non è necessario memorizzare questi — gli esempi di workflow sotto riferiscono tutti di loro.

Esempi di workflow

I tre esempi sotto coprono i modelli più comuni. Tutti utilizzano la stessa forma: controlla il repo, installa le dipendenze, costruisci gli asset web, sincronizza con nativo, poi chiama Capgo Costruisci con credenziali passate come variabili di ambiente.

1. Trigger manuale

Qualsiasi utente con accesso di scrittura può avviare un build dal Actions tab in GitHub con un menu a discesa per piattaforma. Utile per test di ad-hoc o per avviare una release su richiesta.

.github/lavori/capgo-costruzione-manuale.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 }}

Replace com.example.app con il tuo ID dell'app. Una volta commesso, vai a Azioni → Capgo Costruisci (Manuale) → Esegui workflow attivarlo.

per attivarlo. 2. Release su Tag

Costruisce e distribuisce entrambe le piattaforme in parallelo ogni volta che puoi spingere un tag di versione come v1.4.0Questo è il setup di produzione più comune — git tag v1.4.0 && git push --tags diventa il tuo comando di rilascio.

github/lavori/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 esegue iOS e Android in parallelo su esecutori separati. Impostazione fail-fast: false significa che un build iOS fallito non cancella il build Android in corso (e viceversa) — utile quando un piattaforma ha un problema di firma temporaneo.

Note

Informazioni sul numero di versione: Capgo Incrementa automaticamente il numero di build con ogni rilascio. Se preferisci fissarlo al tag, vedi Saltare l'aumento del numero di build di seguito.

3. Costruisci in debug su push a Main

Cattura le regressioni di costruzione native in anticipo producendo un costrutto Android in debug su ogni push a main. È economico da eseguire, fornisce feedback veloce e puoi saltare l'upload su Play Store per mantenerlo esclusivamente come test di fumo.

github/lavori/capgo-costruisci-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

The paths assicura che il workflow non venga eseguito per modifiche esclusivamente documentali. --no-playstore-upload skips la sottoscrizione della Play Store (no PLAY_CONFIG_JSON needed), e --output-upload produce un URL di download per l'APK risultante in modo da poterla installare su un dispositivo di test.

Modelli comuni

Salta l'upload su Play Store / TestFlight

Per costruire test, saltare la sottoscrizione del negozio: Android utilizza --no-playstore-upload; per iOS, costruisci in modalità ad-hoc con --ios-distribution ad_hoc (che non invia mai alla App Store). Combina entrambi con --output-upload per ottenere un URL di download a tempo limitato per il binario.

Invia la release per la revisione della store

Di default, le release di produzione caricano l'artifact firmato e lasciano l'azione finale della store sotto il tuo controllo. Per le release di CI che dovrebbero passare direttamente nella flussi di revisione della store, aggiungi --submit-to-store-review.

Usa il tuo account di servizio. PLAY_CONFIG_JSON account del servizio Senza un tracciamento esplicito, --submit-to-store-review predefinito è il tracciamento di produzione con release_status: completed. È consigliabile specificare il tracciamento nel punto di chiamata con --android-track (o PLAY_STORE_TRACK), e sovrascrivi lo stato quando necessario: --android-release-status / PLAY_STORE_RELEASE_STATUS Copia nel portapenna

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

Per un rilascio interno completato invece che di produzione:

- 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 utilizza la chiave di percorso App Store Connect API e invia la build elaborata di TestFlight alla revisione di App Store. Richiede app_store Distribuzione; --ios-testflight-groups è facoltativo per la distribuzione beta esterna e non è richiesto per la revisione dell'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

Attento!

Questa via invia solo l'artefatto di costruzione. I metadati della lista di store, i gruppi di tester, i dettagli di contatto per la revisione, le risposte di conformità e le scelte di distribuzione devono essere pronti in App Store Connect o Google Play Console prima che i CI li eseguano.

Leggi l'URL di output di costruzione e QR code

Passa --output-record <path> per persistere l'URL dell'artifact di costruzione e il QR code sul disco quando la costruzione ha successo, quindi leggerlo nuovamente nelle fasi successive con build last-output. Nessuna scrittura di log, nessuna 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 scrive un record JSON (con jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) e un QR PNG code accanto a /tmp/build.json.qr.png. build last-output legge di nuovo:

• --field outputUrl stampa solo l'URL di download (terminato da newline; sicuro per URL=$(...)).
• --field qrCodePngPath stampa la strada del PNG in modo che possa caricarlo come allegato PR.
• --qr Stampa la rappresentazione ASCII QR — inseriscila dentro un recinto Markdown code nel commento PR per la lettura inline.

Note

Il record viene scritto solo dopo un build riuscito. Non supportato schemaVersion e sconosciuto --field valori di uscita non sono zero, quindi un CLI obsoleto nel runner fallisce rumorosamente invece di emettere silenziosamente un URL vuoto.

Evita l'aumento del numero di build

Di default ogni build di rilascio incrementa il numero di build. Per fissarlo a un valore che controlli (ad esempio, il tag Git), passa --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 dipendenze

Nota

Questa sezione riguarda GitHub Azioni il caching sul runner CI (locale Pods/ e .gradle prima dell'upload). Capgo mantiene anche un cache build cloud per applicazione sul runner di costruzione (abilitato di default; omettere cache_key per il cache generale condiviso). Passa --cache-key per dividere RC e produzione, o --no-cache per disabilitare il ripristino e il salvataggio. Vedi Risoluzione dei Problemi: ripristino cache errato.

bun install È già abbastanza veloce che una cache dei dipendenze JS non si renda spesso necessaria, ma le dipendenze native di Capacitor (CocoaPods, Gradle) sono comunque utili per i progetti più grandi.

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

Troubleshooting

Symptom	Causa probabile
CAPGO_TOKEN is not set	Segreto non aggiunto, o il lavoro non ha accesso ad esso (controlla le protezioni dell'ambiente/ramo)
Mancano errori di credenziali iOS/Android	gh secret set -f non è stato eseguito, o è stato eseguito su un repository diverso. Verifica con gh secret list
cap sync fallisce in CI ma funziona localmente	Un plugin nativo non è in package.jsono hai dimenticato bun install prima cap sync
Prima di lavorare su una nuova funzionalità, crea un issue e discuti	Errore nell'ID della squadra o l'app non esiste ancora nel App Store Connect. Verifica localmente con bunx @capgo/cli@latest build credentials manage
Il progetto si blocca durante l'upload	Progetto archivio è insolitamente grande — controlla che node_modules La costruzione si blocca dopo 'Caricamento del progetto'
Provisioning profile doesn't match bundle ID	La mappa di provisioning punta a un ID bundle diverso da quello con cui Xcode firma. Riavvia build init per aggiornare il profilo, quindi ri-esporta con build credentials manage
Credenziali cambiate localmente ma l'esecuzione di CI fallisce ancora	Non dimenticare di ri-esportare e ri-pubblicare: bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId>
Il gestore rifiuta di scrivere il file combinato	Le chiavi di configurazione condivise differiscono tra piattaforme — il gestore avverte e chiede conferma. Si può confermare per sovrascrivere, o ri-esportare per piattaforma con --platform ios / --platform android
build last-output Stampa un URL vuoto	La costruzione non è riuscita --output-uploado è fallita prima di produrre un artefatto. outputUrl sarà null nel registro. Sulla branca [ -n "$URL" ] prima di utilizzarlo
build last-output errori con Unsupported record schemaVersion	Il runner è su una versione più vecchia di CLI rispetto a quella che ha scritto il record. Assicurati che sia la stessa versione per produttore e lettore (ad esempio bunx @capgo/cli@7.104.0 … su entrambi i lati) piuttosto che @latest, che fluttua e può spostarsi tra i job

Per fallimenti di build specifici della piattaforma, vedere il Guida di risoluzione dei problemi.

Prossimi Passaggi

Auto OTA o Nativo CI tra caricamento di live update e costruzione di Capgo

Attiva da UI di CI Esegui costruzione di Capgo dalla scheda Azioni su richiesta.

Costruisci Webhooks Inizia lo stesso workflow da un'istanza di dashboard HTTP.

Credenziali di accesso Riferimento completo per la preparazione delle credenziali iOS e Android come segreti base64.

Opzioni di configurazione Tutti i CLI flag e variabili di ambiente per l'ottimizzazione dei tuoi build.