GitHub Azioni

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

Automatizza le tue costruzioni iOS e Android direttamente dal tuo repository GitHub. Con un file di workflow unico e un piccolo numero di segreti del repository, ogni push, tag o trigger manuale può produrre app firmate e pronte per il magazzino — senza che nessun membro dello staff abbia bisogno di un Mac, Xcode o Android Studio installati.

Cosa Otterrai

Rilasci senza Intervento

Etichetta un rilascio nel Git e le tue app iOS e Android firmate vengono inviate automaticamente a TestFlight e Play Store.

Setup Locale Non Richiesto

Contribuenti su Windows o Linux possono attivare le build per iOS. Nessun Xcode, nessun problema di provisioning, nessun certificato di firma condiviso che gira intorno ai portatili.

Segreti a livello di ambito

I segreti vivono nei segreti del repository GitHub, a livello di ambito per il tuo repository e visibili solo al runner del workflow. Facile da rotare, facile da auditare.

Costruzioni parallele

Costruisci iOS e Android allo stesso tempo con un lavoro di matrice. Una tipica rilascio 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 lo sei)
Configura le credenziali di build locali con bunx @capgo/cli@latest build init — vedi Gestione delle credenziali per la guida passo passo del wizard
Un build locale riuscito (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — il CI non è il posto giusto per debuggare il tuo primo build
Il GitHub CLI (gh) installato e autenticato (gh auth login)

Setup

The Capgo CLI can export your local credentials as a ready-to-use .env Il __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ può esportare le tue credenziali locali come un file pronto all'uso gh secret set -fCombinato con

Add your Capgo API key as a repository secret

Aggiungi la tua API __CAPGO_KEEP_1__ chiave come un segreto del repository
La __CAPGO_KEEP_0__ chiave non fa parte del magazzino di credenziali per app, quindi aggiungila una volta manualmente:
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Copia nel portapenna Genera la chiave nel Capgo dashboard con carica o un livello di autorizzazione superiore.
Esporta le tue credenziali in un .env file

Eseguire il gestore delle credenziali interattivo:
Fermata dei comandi
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Nella TUI, seleziona Esporta in .env. Il CLI scrive .env.capgo.<appId> a directory corrente con modalità 0600 (proprietario-leggibile solo) — ad esempio .env.capgo.com.example.app. Quando sono configurati sia iOS che Android, le chiavi segrete di entrambe le piattaforme vengono salvate nello stesso file sotto # === IOS === e # === ANDROID === i titoli della sezione. 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 il manager a una piattaforma. L'esportazione produce quindi un file per piattaforma come .env.capgo.com.example.app.iosUtili quando le chiavi segrete di iOS e Android sono presenti in repository o ambienti diversi.

A pochi 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 diventati diversi. Se il gestore 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 Actions

La gh secret set -f comanda legge un file dotenv e crea un segreto repository per KEY=value linea:
Fenestra del terminale
```
gh secret set -f .env.capgo.com.example.app
```
È tutto — ogni segreto che il tuo workflow ha bisogno è ora in GitHub. Verifica con gh secret list.
Don't commit il file .env
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Finestra del terminale
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Re-export anytime you need to rotate credentials — the file isn’t a long-lived artifact.
Creare il file di workflow

Aggiungi .github/workflows/capgo-build.yml alla tua repository. Scegli uno dei tre modelli di trigger sotto, a seconda di come desideri attivare le costruzioni.

Cosa finisce nella tua sezione segreti

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

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 sotto riportati già fanno riferimento a tutti di loro.

Esempi di workflow

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

1. Trigger manuale

Consente a chiunque abbia accesso di scrittura di avviare un build dal azioni tabella in GitHub con un menu a discesa per piattaforma. Utile per costruire ed eseguire test 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'applicazione. Una volta commesso, vai a azioni → Capgo Costruzione (Manuale) → Esegui workflow 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.

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

Il 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. Debug Build on Push to Main

Cattura le regressioni di costruzione nativa in anticipo producendo un costrutto Android in modalità debug su ogni push a main. Economico da eseguire, feedback veloci e puoi saltare l'upload su Play Store per mantenerlo puramente come 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

La paths filtra per assicurarsi che il flusso di lavoro non venga eseguito su modifiche esclusivamente documentali. --no-playstore-upload salta la sottoscrizione su Play Store (nessuna PLAY_CONFIG_JSON è necessaria), e --output-upload produce un URL di download per il file APK risultante in modo che tu possa installarlo su un dispositivo di test.

Patterni Comuni

Saltare l'upload di Play Store / TestFlight

Per le build di test, saltare la sottoscrizione al 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 una URL di download temporanea per il file binario.

Sottopone la versione di store alla revisione

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

Android utilizza il tuo PLAY_CONFIG_JSON account di servizio. Senza una pista esplicita, --submit-to-store-review si attiva il tracciato di produzione con release_status: completed. Preferire indicare il tracciato al sito di chiamata con --android-track o PLAY_STORE_TRACK, e sovrascrivere lo stato con --android-release-status / PLAY_STORE_RELEASE_STATUS quando necessario:

- 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 al posto di quello 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 il build elaborato di TestFlight per la revisione di App Store. Richiede app_store la 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 di costruzione e QR code

Passa --output-record <path> per persistere l'URL di artefatto di costruzione e QR code sul disco quando la costruzione ha successo, poi leggilo nuovamente in passaggi successivi con build last-outputSenza scrittura di 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, finishedAte un QR code PNG accanto a /tmp/build.json.qr.png. build last-output leggilo nuovamente:

--field outputUrl stampa solo l'URL di download (terminato da nuova riga; sicuro per URL=$(...)).
--field qrCodePngPath stampa il percorso del file PNG in modo che possa essere caricato come allegato di PR.
--qr stampa l'immagine QR ASCII generata - inseriscila dentro un recinto di Markdown code nella commento di PR per la lettura 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

Cache dipendenze

bun install è già abbastanza veloce che un cache delle dipendenze JS è raramente redditizio, ma le dipendenze native di Capacitor (CocoaPods, Gradle) sono comunque 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`	La chiave segreta non è stata aggiunta, o il job non ha accesso ad essa (controlla 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 in CI ma funziona localmente	A plugin nativo non è presente `package.json`o hai dimenticato `bun install` prima `cap sync`
Creare un problema e discutere prima di lavorare su una nuova funzione	Costruire ha successo ma non compare l'applicazione in App Store Connect `bunx @capgo/cli@latest build credentials manage`
L'ID del team è sbagliato o l'app non esiste ancora in App Store Connect. Verifica localmente con	Costruzione bloccata dopo 'Caricamento del progetto' `node_modules` Il file di archiviazione del progetto è insolitamente grande — controlla che
`Provisioning profile doesn't match bundle ID`	non stia caricando (non dovrebbe farlo di default) `build init` Il mapping di provisioning punta a un ID di bundle diverso da quello con cui Xcode sta firmando. Esegui nuovamente `build credentials manage`
per aggiornare il profilo, poi esporta nuovamente con	Il cambio delle credenziali locali ma il CI fallisce ancora una volta non dimenticare di ri-esportare 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 fallì prima di produrre un artefatto. `outputUrl` sarà `null` nel registro. Sulla branca `[ -n "$URL" ]` prima di utilizzarlo
`build last-output` con `Unsupported record schemaVersion`	l'esecutore è su una versione più vecchia di CLI rispetto a quella che ha scritto il registro. Assicurati di fissare sia il produttore che il lettore alla stessa versione esplicita (ad esempio `bunx @capgo/cli@7.104.0 …` su entrambi i lati) piuttosto che `@latest`, che fluttua e può deviare tra i job

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

Esegui i passaggi successivi

Auto OTA o Nativo CI tra l'upload di aggiornamento live e Capgo Build.

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

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

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

Opzioni di configurazione Tutte le CLI flag e variabili di ambiente per la fine-tunatura delle tue build.