GitHub Azioni

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Automatizza le tue compilazioni iOS e Android direttamente dal tuo repository GitHub. Con un file di workflow e un piccolo numero di segreti del repository, ogni push, tag o trigger manuale può produrre app firmate e pronte per il deposito — senza che nessun membro del team debba avere un Mac, Xcode o Android Studio installati.

Cosa Otterrai

Lanci senza Intervento

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

Setup Locale Non Richiesto

I contribuenti su Windows o Linux possono attivare le compilazioni iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira tra i laptop.

Segreti Scoperti

Le credenziali vivono nel repository GitHub segreti, limitati al tuo repo e visibili solo al runner del workflow. Facile da rotare, facile da auditare.

Costruzioni parallele

Costruisci iOS e Android allo stesso tempo con un job di matrice. Una tipica release si conclude in meno di 10 minuti.

Requisiti preliminari

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 del mago
Una costruzione locale riuscita (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — il CI non è il posto per debuggare la tua prima costruzione
La GitHub CLI (gh) installato e autenticato (gh auth login)

Configurazione

La Capgo CLI può esportare le tue credenziali locali come un file pronto all'uso. .env Combinato con gh secret set -fciò trasforma l'intero setup CI/CD in tre comandi — nessuna codifica base64 manuale, nessuna gestione JSON, nessuna copia-incolla-segreti-segreti.

Aggiungi la tua Capgo API chiave come un segreto del repository

La API chiave non fa parte del magazzino di credenziali per applicazione, quindi aggiungila una volta manualmente:
Fermata di comando
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Genera la chiave nel Capgo dashboard con l'upload o permessi superiori.
Esporta le tue credenziali in un .env file

Esegui il gestore delle credenziali interattivo:
Fenestra del terminale
```
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 (lettura esclusiva del proprietario) — ad esempio, .env.capgo.com.example.app. Quando sia iOS che Android sono configurati, le segrete di entrambe le piattaforme finiscono nel medesimo file sotto # === IOS === Ecco i titoli di sezione. I nomi delle variabili per iOS e Android sono disgiunti, quindi combinare i due è conflitto-free. # === ANDROID === Hai bisogno di un file per piattaforma?

(o --platform ios ) per limitare il manager a una sola piattaforma. L'esportazione produce poi un file per piattaforma come --platform androidÈ utile quando i segreti di iOS e Android sono archiviati in repository o ambienti diversi. .env.capgo.com.example.app.iosChiavi di configurazione condivise

) possono essere archiviate separatamente per ogni piattaforma e potrebbero essere diventate diverse. Se il manager trova delle differenze, stampa le chiavi in conflitto, chiede una conferma esplicita prima di scrivere e inserisce la lista dei conflitti come commento all'inizio del file. Ri-esporta conBUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION__CAPGO_KEEP_0__ --platform Se hai bisogno di preservare valori per piattaforma.
Spingi il .env file a GitHub Secrets delle azioni

Il gh secret set -f comando legge un file dotenv e crea un segreto repository per KEY=value riga:
Finestra del terminale
```
gh secret set -f .env.capgo.com.example.app
```
Ecco fatto — ogni segreto che il tuo workflow richiede è ora in GitHub. Verifica con gh secret list.
Non commettere il file .env
Viene utilizzato materiale di firma in testo puro. Una volta che l'avrai spinto in GitHub:
Finestra del terminale
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Ri-esporta in qualsiasi momento avrai bisogno di ruotare le credenziali — il file non è un artefatto a lunga durata.
Creare il file di workflow

Aggiungi .github/workflows/capgo-build.yml a tuo repository. Scegli uno dei tre modelli di trigger sotto, a seconda di come vuoi far partire le costruzioni.

Cosa finisce nelle tue segrete

Per riferimento, gh secret set -f creerà questi segreti del repository (il tuo file YAML di workflow li fa riferimento 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`
(aggiunto manualmente)	`CAPGO_TOKEN`

Non è necessario memorizzare questi — gli esempi di workflow riportati di seguito già fanno riferimento a tutti di loro.

Esempi di Flusso di Lavoro

Gli esempi riportati di seguito coprono i modelli più comuni. Tutti utilizzano la stessa forma: scaricare il repository, installare le dipendenze, creare gli asset web, sincronizzare con nativo, quindi chiamare Capgo Costruisci con le credenziali passate come variabili di ambiente.

1. Trigger Manuale

Consente a chiunque abbia accesso di scrittura di avviare un build dal Azioni tab in GitHub con un menu a discesa per la piattaforma. Utile per test di ad-hoc o per avviare una release su richiesta.

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

Sostituisci con l'ID del tuo app. Una volta commesso, vai a com.example.app Azioni → __CAPGO_KEEP_0__ Costruisci (Manuale) → Esegui workflow Actions → Capgo Build (Manual) → Run workflow 2. Rilascia su Tag

Sezione intitolata “2. Rilascia su Tag”

Questo è il setup di produzione più comune — v1.4.0diventa il tuo comando di rilascio. git tag v1.4.0 && git push --tags __CAPGO_KEEP_0__/workflow/__CAPGO_KEEP_1__-costruzione-rilascio.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. Impostare fail-fast: false significa che un build iOS fallito non cancellerà il build Android in corso (e viceversa) — utile quando una piattaforma ha un problema di firma temporaneo.

3. Costruisci in modalità debug su push a Main

Cattura le regressioni di costruzione nativa in modo tempestivo producendo un build Android in modalità debug con ogni push a main. Economico da eseguire, feedback veloce, e puoi saltare l'upload su Play Store per mantenerlo puramente un test di fumo.

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

Il paths Il filtro assicura che il flusso di lavoro non venga eseguito su modifiche esclusivamente documentali. --no-playstore-upload salta l'invio su Play Store (non PLAY_CONFIG_JSON necessario), e --output-upload produce un URL di download per l'APK risultante in modo che tu possa installarlo su un dispositivo di test.

Modelli comuni

Salta l'upload su Play Store / TestFlight

Per le costruzioni di 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 temporaneo per il binario.

Sottoponi la versione di rilascio per la revisione

Di default, i rilasci caricano l'artefatto firmato e lasciano l'azione finale del negozio sotto il tuo controllo. Per le rilasci di CI che dovrebbero muoversi direttamente nel flusso di revisione del negozio, aggiungi --submit-to-store-review.

Android utilizza il tuo PLAY_CONFIG_JSON servizio di account e sottopone la versione di rilascio di Google Play al posto di lasciarla inattiva. Aggiungi --store-release-name, --store-release-notes, e opzionali --store-release-notes-locale entrata quando desideri che la versione di rilascio di Play porti lo stesso tag e le note di rilascio localizzate come 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 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 di 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

Leggi l'URL di output della build e il QR code

Passa --output-record <path> per persistere l'URL e il QR code dell'artifact della build sul disco quando la build ha successo, quindi leggilo nuovamente nelle fasi successive senza log scraping, senza regex. build last-outputPass

- 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 il percorso del PNG in modo che possa essere caricato come allegato PR.
--qr stampa il QR ASCII reso — lascialo all'interno di un recinto Markdown code per la scannabilità inline.

Saltare l'incremento del numero di build

Di default ogni 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

bun install è già abbastanza veloce che un cache delle dipendenze JS non è spesso redditizio, ma le dipendenze native di Capacitor (CocoaPods, Gradle) sono degne di essere cacheate 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') }}

Risoluzione dei problemi

Sintomo	Causa probabile
`CAPGO_TOKEN is not set`	Non è stato aggiunto il segreto, o il lavoro non ha accesso ad esso (controlla le protezioni ambiente/branch)
Errore di credenziali iOS / Android mancanti	`gh secret set -f` non è stato eseguito, o è stato eseguito contro un repository diverso. Verifica con `gh secret list`
`cap sync` fallisce in CI ma funziona localmente	Un plugin nativo non è in `package.json`, o ti sei dimenticato `bun install` prima `cap sync`
La costruzione ha successo ma non compare l'app in App Store Connect	L'ID del team è sbagliato, o il record dell'app non esiste ancora in App Store Connect. Verifica localmente con `bunx @capgo/cli@latest build credentials manage`
La costruzione si blocca dopo 'Caricamento del progetto'	L'archivio del progetto è insolitamente grande — controlla che `node_modules` non stia venendo caricato (non dovrebbe farlo di default)
`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 rieporta con `build credentials manage`
Le credenziali sono state modificate localmente ma il CI continua a fallire	Non dimenticare di rieportare e ri-pubblicare: `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Il manager rifiuta di scrivere il file combinato	Le chiavi di configurazione condivise differiscono tra piattaforme — il manager avverte e chiede conferma. Si conferma per sovrascrivere, o si rieporta per piattaforma con `--platform ios` / `--platform android`
`build last-output` Stampa un URL vuoto	Il build non è riuscito `--output-upload`, o è fallito prima di produrre un artefatto. `outputUrl` sarà `null` nel registro. Sviluppa su `[ -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 il produttore che il lettore siano fissati alla stessa versione esplicita (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`che galleggia e può spostarsi tra i lavori

Per fallimenti di costruzione specifici della piattaforma, vedi il Guida di risoluzione dei problemi.

Passaggi successivi

Auto OTA o Nativo CI di branch tra upload di aggiornamento in tempo reale e Capgo Build.

Avvia da CI UI Esegui Capgo Build dalla scheda Azioni su richiesta.

Costruire Webhooks Avvia lo stesso workflow da una chiamata HTTP da dashboard amministrativo.

Impostazione Credenziali 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 la fine-tunatura delle tue build.