GitHub Azioni

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

Automate le tue build iOS e Android direttamente dal tuo repository GitHub.

What You Get

Rilasci senza intervento

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

Setup locale non necessario

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

Segreti a scopo

I credenziali vivono nei segreti del repository GitHub, a scopo del tuo repo e visibili solo al runner di workflow. Facile da rotare, facile da auditare.

Build paralleli

Costruisci iOS e Android allo stesso tempo con un lavoro di matrice. Un rilascio tipico 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 una Capgo API chiave
La tua app registrata in Capgo (bunx @capgo/cli@latest app add se non è così)
Le credenziali di build configurate localmente con bunx @capgo/cli@latest build init — vedi Gestione delle Credenziali per la guida passo passo del wizard
Una build 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 build
The GitHub CLI (gh) installato e autenticato (gh auth login)

Configurazione

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

Aggiungi la tua chiave Capgo API come segreto del repository

La chiave API non fa parte del repository dei credenziali per-app, quindi aggiungila manualmente una volta:
Finestra del terminale
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Genera la chiave nel Capgo dashboard con permessi di caricamento o superiore. Esporta le tue credenziali in un
file .env Esegui il gestore interattivo delle credenziali:

Esegui il gestore interattivo delle credenziali:
Finestra del terminale
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Nella TUI, seleziona Esporta in .envIl CLI scrive .env.capgo.<appId> nella tua directory corrente con modalità 0600 (solo lettura del proprietario) — ad esempio, .env.capgo.com.example.appQuando entrambe iOS e Android sono configurate, i segreti di entrambe le piattaforme finiscono nello stesso file sotto # === IOS === e # === ANDROID === I nomi delle variabili di ambiente per iOS e Android sono disgiunti, quindi combinare le due è conflitto-free.

Passa --platform ios (o --platform android) per limitare lo scope del manager a una piattaforma. L'esportazione produce quindi un file per piattaforma come .env.capgo.com.example.app.ios. Utile quando i segreti di iOS e Android vivono in repository o ambienti diversi.

Un piccolo numero di interruttori di configurazione (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) possono essere memorizzati sotto ogni piattaforma in modo autonomo e possono essere stati spinti lontano. 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.
Spingi il .env file a GitHub segreti di Actions

La gh secret set -f Il comando legge un file dotenv e crea un segreto repository per linea: KEY=value Finestra del terminale
Copia nel portapenne
```
gh secret set -f .env.capgo.com.example.app
```
That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.
Contiene materiale di firma in testo piano. Una volta che l'avrai spinto su __CAPGO_KEEP_0__:
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Copia nel portapenne
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Crea il file di workflow
Finestra del terminale

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

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`
(aggiunti manualmente)	`CAPGO_TOKEN`

Non hai bisogno di memorizzare questi — gli esempi di workflow sotto già fanno riferimento a tutti di loro.

Esempi di Flusso di Lavoro

I tre esempi che seguono coprono i modelli più comuni. Tutti utilizzano la stessa forma: controlla il repository, installa le dipendenze, costruisci gli asset web, sincronizza con nativo, quindi chiama 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 Pulsante tab in GitHub con un menu a discesa di 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 com.example.app con il tuo ID dell'app. Una volta commesso, vai a Azioni → Capgo Costruisci (Manuale) → Esegui flusso di lavoro per attivarlo.

2. Rilascia su Tag

Costruisce e distribuisce sia le piattaforme che 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.

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 runner separati. Impostare fail-fast: false significa che un costruzione iOS fallita non cancellerà il costruzione Android in corso (e viceversa) — utile quando una piattaforma ha un problema di firma temporaneo.

Sezione intitolata “3. Costruzione di debug su push a Main”

A basso costo, feedback veloci e puoi saltare l'upload su Play Store per mantenerlo esclusivamente come test di fumo. main__CAPGO_KEEP_0__/workflows/__CAPGO_KEEP_1__-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

Il paths assicura che il workflow non venga eseguito per modifiche solo documentali. --no-playstore-upload salta la sottoscrizione alla Play Store (non necessario) e PLAY_CONFIG_JSON produce un URL di download per l'APK risultante in modo che possa installarlo su un dispositivo di test. --output-upload Modelli Comuni

Sezione intitolata “Modelli Comuni”

Sezione intitolata “Salta l'upload alla Play Store / TestFlight”

; per iOS, costruisci in modalità ad-hoc con --no-playstore-upload(che non invia mai alla App Store). Combina entrambi con --ios-distribution ad_hoc per ottenere un URL di download a tempo limitato per il binario. --output-upload For test builds, skip store submission: Android uses __CAPGO_KEEP_0__; for iOS, build in ad-hoc mode with __CAPGO_KEEP_1__ (which never submits to the App Store). Combine either with __CAPGO_KEEP_2__ to get a time-limited download URL for the binary.

Invia la versione del negozio per la revisione

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

L'Android utilizza il tuo PLAY_CONFIG_JSON account di servizio e invia 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 entry quando desideri che la versione di rilascio di Play trasporti 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}"

L'iOS utilizza la chiave di percorso App Store Connect API e invia la versione elaborata di TestFlight per la revisione di App Store. Richiede app_store distribuzione; --ios-testflight-groups è opzionale per la distribuzione beta esterna e non è richiesta 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 di costruzione e QR code

Passa --output-record <path> per persistere l'URL dell'artefatto di costruzione e QR code sul disco quando la costruzione ha successo, quindi leggilo nuovamente nelle fasi successive con build last-outputSenza scavo dei log, senza 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 code in PNG accanto a /tmp/build.json.qr.png. build last-output leggilo nuovamente:

--field outputUrl Stampa solo l'URL di download (terminato da nuovo riga; sicuro per URL=$(...)).
--field qrCodePngPath Stampa la percorso PNG in modo che possa caricarlo come allegato di PR.
--qr Stampa l'ASCII QR generato — inseriscilo dentro un recinto Markdown code nella commento di PR per la scannabilità inline.

Saltare 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

Dipendenze della cache

bun install è già abbastanza veloce che una cache delle dipendenze JS è raramente redditizia, ma le dipendenze native di Capacitor (CocoaPods, Gradle) sono comunque utili da cache 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') }}

Risolvere i problemi

Sintomo	Causa probabile
`CAPGO_TOKEN is not set`	Segreto non aggiunto, o il lavoro non ha accesso ad esso (verifica le protezioni dell'ambiente/branch)
Errori di credenziali iOS/Android mancanti	`gh secret set -f` non è stato eseguito, o è stato eseguito su un repository diverso. Verifica con `gh secret list`
`cap sync` fallisce nel CI ma funziona localmente	A plugin nativo non è presente `package.json`o hai 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 essendo caricato (non dovrebbe essere di default)
`Provisioning profile doesn't match bundle ID`	Il mapping di provisioning punta a un ID bundle diverso da quello con cui Xcode sta firmando. Riavvia `build init` per aggiornare il profilo, poi rieporta con `build credentials manage`
Il credenziale sono state cambiate localmente ma il CI fallisce ancora	Dimenticati 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 esporta nuovamente per piattaforma con `--platform ios` / `--platform android`
`build last-output` stampa un URL vuoto	La costruzione non è riuscita `--output-upload`o è fallita prima di produrre un artefatto. `outputUrl` sarà `null` nel registro. Sulla branca di `[ -n "$URL" ]` prima di utilizzarlo
`build last-output` con errori in `Unsupported record schemaVersion`	Il runner è su una versione più vecchia di CLI rispetto a quella che ha scritto il registro. Si fissi la stessa versione esplicita per produttore e lettore (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`, che fluttua e può deviare tra i job

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

Passaggi successivi

Configurazione delle credenziali Riferimento completo per la preparazione delle credenziali iOS e Android come segreti base64.

Costruzioni iOS Guida più approfondita per certificati, profili e invio all'App Store.

Costruzioni Android Configurazione del keystore, account di servizio Play Store e gestione dei flavor.

Opzioni di configurazione Tutti i CLI flag e variabili di ambiente per una fine-tuning dei costruttori.