iOS Builds

Costruisci e invia app iOS su TestFlight e l'App Store utilizzando l'infrastruttura Mac dedicata di Capgo.

Cosa imparerai

• Imparerai a caricare il tuo app tramite Capgo Native build
• Imparerai a configurare i certificati per Capgo Native Build

Requisiti preliminari

• Un account Capgo (un trial gratuito è sufficiente per iniziare)
• La tua app già registrata in Capgo (esegui bunx @capgo/cli@latest app add se non si applica), Un computer Mac con Xcode installato (è possibile configurare la compilazione su una macchina Linux/Windows, ma non è ancora documentato)
• Una sottoscrizione valida di Apple Developer ($99/all'anno) (Devi avere diritti di amministratore o proprietario sull'account Apple Developer)
• Il tuo app deve essere in grado di compilarsi con successo tramite Xcode
• Un app __CAPGO_KEEP_0__
• A Capacitor app
• Nota

Utilizzerò l'app seguente per il tutorial:

https://__CAPGO_KEEP_0__.com/Cap-go/__CAPGO_KEEP_1__-native-build-tutorial-app https://github.com/Cap-go/capgo-native-build-tutorial-app

Sezione intitolata “Prima di iniziare nei portali di Apple”']}

Prima di configurare i certificati o di attivare l'upload di TestFlight, assicurati che l'account Apple e il team siano pronti:

• Attiva l'autenticazione a due fattori per l'account Apple utilizzato per l'iscrizione
• Scegli il tipo di abbonamento giusto:
  • Individuale / Proprietario unico: il tuo nome personale diventa il nome del venditore sull'App Store
  • Organizzazione: richiede un'entità legale, un numero D-U-N-S, un sito web aziendale pubblico, un indirizzo email di lavoro sul dominio della società e una persona con l'autorità di vincolare l'organizzazione agli accordi di Apple
• Usa un account che possa accedere sia a Apple Developer che a App Store Connect per i certificati, i record dell'app, le chiavi API e TestFlight
• Blocca il tuo ID bundle finale presto. Cambiarlo in seguito significa di solito ricominciare la configurazione dell'App Store
• Pianifica questi elementi di App Store Connect prima della revisione dell'app: URL del supporto, URL della politica sulla privacy, età di accesso, screenshot, conformità all'esportazione e dettagli di contatto per la revisione dell'app

Nota

Riferimenti ufficiali utili:

• Diventa membro del programma sviluppatore Apple
• Invia le tue app e i giochi
• Informazioni sulla versione della piattaforma in App Store Connect

Attenzione

Apple aggiorna regolarmente il requisito minimo di SDK. A partire dal 28 aprile 2026iPhone e iPad app pubblicati su App Store Connect devono essere costruiti con il iOS & iPadOS 26 SDK o versione successiva.

Consigliato: onboarding automatizzato

Non dovete fare nulla di tutto ciò a mano. L'onboarding di Capgo crea e configura i vostri credenziali di firma iOS (certificato di distribuzione + profilo di provisioning) per voi — questo è il percorso consigliato:

bunx @capgo/cli@latest build init --platform ios

La guida manuale di seguito è solo per coloro che preferiscono configurare le credenziali da soli o desiderano capire esattamente cosa Capgo fa sotto la pelle.

La prima costruzione manuale

Prima di poter iniziare a pensare a costruire l'app con Capgo, dovremmo prima configurarlo e fare una prima costruzione di TestFlight a mano. Ci sono alcuni vantaggi nel fare una costruzione manuale prima:

• Configurerete il certificato di distribuzione sul vostro computer locale
• Creerai il record dell'App Store se non l'hai fatto ancora
• Potrai risolvere qualsiasi problema con il processo di costruzione collegato alla tua app code

Prima di poter iniziare, devi avere l'installato il certificato di distribuzione sul tuo computer locale. Questo è un po' complesso, ma ti spiegherò di seguito.

Configurazione del certificato di distribuzione

1. Apre Xcode

2. Clicca su Xcode -> Settings... Alternativamente, puoi utilizzare la scorciatoia Cmd + ,

   

3. Vai a Accounts

4. Cerca l'Account Apple aggiunto all'Account dello Sviluppatore Apple

5. Trova l'equipe che utilizzerai per distribuire l'app

6. Clicca sul Manage Certificates... tasto

7. Assicurati di poter vedere il certificato di distribuzione nella lista

8. Se non lo vedi, devi creare un nuovo certificato

   Nota

   Apple limita il numero di certificati di distribuzione che puoi avere a 3. Se hai più di 3 certificati, devi eliminare uno per poter crearne uno nuovo. Non coprirò questo argomento nel tutorial.

   1. Click sul + e poi su Apple Distribution
   2. Il certificato verrà creato automaticamente. Puoi vederlo nella lista. Guarda il passaggio precedente per confermare che lo vedi.

Ora che hai installato il certificato di distribuzione, puoi iniziare il processo di build.

Build manuale per TestFlight

1. Apre l'applicazione in Xcode

   Esegui bunx cap open ios per aprire l'applicazione in Xcode.

2. Cerca e clicca sul archive bottoni

   Nella bar degli strumenti di Xcode, trova e clicca sul product -> archive pulsante.

   

3. Aspetta che la compilazione sia completa

4. Clicca sul Distribute App pulsante

   

5. Seleziona TestFlight Internal Only come metodo di distribuzione e clicca su Distribute pulsante

   

6. Configura il record dell'app

   Compilare i seguenti campi:

   1. Nome: il nome del tuo app - visibile nella App Store
   2. SKU - lo SKU del tuo app - questo viene utilizzato per identificare il tuo app nella App Store
   3. La lingua principale - la lingua principale del tuo app

   Poi, clicca sul next tasto

   

7. Se la creazione del record dell'app fallisce, prova a chiudere la finestra e prova a creare un archivio dell'app di nuovo.

8. Aspetta che l'upload sia completo

9. Se tutto è andato bene, dovresti vedere la seguente schermata

10. Clicca sul Done button

Potresti avere l'istinto di pensare che tutto sia adesso buono e che potrai vedere la tua app in TestFlight, ma ci sono ancora alcune cose da finire:

1. Aggiungiti a TestFlight
2. Completa l'adeguamento alle norme di esportazione per rendere il build testabile
3. Compila i metadati obbligatori di App Store Connect, come l'URL del tuo supporto, l'URL della tua politica sulla privacy e la classificazione di età
4. Prepara le schermate che corrispondono ai dispositivi che effettivamente supporti
5. Aggiungi i dettagli di contatto per la revisione dell'app e qualsiasi credenziale di test prima della sottoscrizione di produzione

Iniziamo con la prima:

Aggiungerti a TestFlight

1. Vai al App Store Connect pagina

2. Accedi con il tuo account di sviluppatore Apple

3. Seleziona l'equipe che hai utilizzato quando hai creato il record dell'app. Se hai solo un account di sviluppatore, puoi saltare questo passaggio.

4. Clicca sul Apps tasto

5. Trova l'app che hai creato nel passaggio precedente e clicca su di essa

6. Clicca sul TestFlight tasto

7. Clicca sul Internal Testers plus button

8. Crea un nuovo gruppo

   Mi piace chiamare il gruppo “interni”. Puoi chiamarlo come vuoi.

   

9. Clicca su Invite testers button

10. Aggiungiti al gruppo

    Trova te stesso nella lista e seleziona la casella accanto al tuo nome. (Potresti dover ricaricare la pagina per vederlo) Poi, clicca su Add button.

    

11. Verifica di essere stato aggiunto al gruppo

    Ora dovresti vedere te stesso nel gruppo.

    

Congratulazioni 🎉 Hai aggiunto te stesso a TestFlight. Ora, c'è solo una cosa in più che devi fare prima di poter configurare Capgo Native Build.

Impostazione delle informazioni sulla conformità

Ora devi promettere ad Apple che la tua app non utilizza alcuna crittografia non standard (come un algoritmo personalizzato). Se la tua app utilizza alcuna crittografia non standard, ti consiglio di leggere il documentazione di Apple su come gestire questo. Ci sono due modi per farlo:

1. Puoi farlo a mano ogni volta che costruisci l'app.
2. Puoi configurare il tuo file plist per impostare automaticamente questo valore a false.

Iniziamo con il primo:

1. Segui tutte le fasi della sezione precedente per trovare la sezione TestFlight in App Store Connect

2. Clicca su Builds -> iOS

3. Trova la build con informazioni di conformità mancanti e clicca su Manage

4. Seleziona l'opzione che meglio descrive la tua app

   Per me, questo è none, ma potrebbe essere diverso per te. Dopo, clicca su

   

5. La tua app dovrebbe ora dire ready to test

   

Per il secondo, ecco i passaggi:

1. Apri il Info.plist file

2. Aggiungi la seguente chiave:

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. Salva il file

Nota

Ecco la documentazione ufficiale di Apple su come informare Apple della tua conformità alle norme di esportazione di cifratura.

Installa l'app TestFlight e accetta l'invito

Ora, sei PRATICAMENTE pronto per testare la tua app in TestFlight. Prima, devi fare le seguenti cose:

1. Scarica l'app TestFlight dalla App Store sul tuo dispositivo iOS/iPadOS
2. Accetta l'invito per testare la tua app

Saltarei i dettagli su come installare l'app TestFlight sul tuo dispositivo. Se non sei sicuro di come installare un'app, Google ha alcune guide fantastiche su come farlo.

Per quanto riguarda l'accettazione dell'invito, riceverai un'email da Apple con un link per accettare l'invito.

1. Apri l'email da Apple con il link per accettare l'invito

2. Clicca su View in TestFlight button

3. Clicca sul Install button

4. Installa l'app sul tuo dispositivo

   Se hai già installato l'app utilizzando Xcode, potresti vedere lo schermo seguente. Clicca sul install button.

5. Aspetta che l'app si installi

6. Clicca sul Open button e cliccalo

Congratulazioni 🎉 Hai accettato l'invito per testare il tuo app in TestFlight. Ora, puoi configurare Capgo Build Nativo per costruire e inviare il tuo app a TestFlight.

Configurazione di Capgo Build Nativo

C'è bisogno di configurare alcune cose in Capgo Build Nativo per poter costruire e inviare il tuo app a TestFlight. Ecco una lista delle cose che passerai al Capgo CLI:

Parametro	Descrizione
--platform	La piattaforma da costruire (ios)
--apple-team-id	Il tuo ID di team dello sviluppatore Apple (trovabile in Portale dello sviluppatore Apple)
--apple-key	Percorso del tuo file API Key di App Store Connect (.p8 file
--apple-key-id	L'ID della tua chiave API di App Store Connect
--apple-issuer-id	Il tuo ID emittente di App Store Connect
--certificate	Percorso del tuo certificato di distribuzione (.p12 file)
--ios-provisioning-profile	Mappatura del profilo di provisioning (bundleId=path o semplicemente percorso per un profilo singolo)

Esempio di comando:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

ID del team

Iniziamo con l'ID del team. Trovarlo è piuttosto facile.

1. Vai a Account del Developer Apple e scorrere verso il basso

2. Trova la Team ID

   

Apple key, Apple key ID e Apple issuer ID

Ora, passiamo all'Apple key.

1. Accedi a pagina dell'utente e della gestione di App Store Connect

   Nota

   Per me il link non funziona a volte. Ricarica la pagina se non funziona per te.

2. Scegli la squadra corretta a discesa

   1. Clicca sul tuo nome nell'angolo in alto a destra
   2. Clicca sulla squadra che vuoi utilizzare

3. Clicca sul Integrations tasto

4. Trova il issuer

   Attenzione

   Questo DEVE ESSERE SALVATO - avrai bisogno di esso in seguito

   Clicca sul copy tasto per copiare l'emittente

5. Clicca sul pulsante '+'

6. Imposta il nome della chiave e impostare l'accesso a App manager e clicca sul Generate tasto

7. Salva l'ID della chiave

   Attenzione

   Questo DEVE ESSERE SALVATO - lo avrai bisogno in futuro

   

8. Scarica la chiave

   Attenzione

   Questo DEVE ESSERE SALVATO - lo avrai bisogno in futuro

   Danger

   NEVER CONDIVIDI LA CHIAVE CON ALTRI - USALA SOLO NEL CAPGO CLI

   

   

Congratulazioni 🎉 Hai creato la chiave Apple, l'ID chiave Apple e l'ID rilasciatore Apple.

Certificato

Ora sei pronto ad esportare il certificato. Come ricorderai, uno dei primi passaggi di questa guida era la configurazione del certificato di distribuzione.

Tuttavia, Apple, nella loro infinita saggezza, ha deciso che il modo in cui esportare il certificato è molto diverso da quello in cui crearli 🙃 Vediamo di capire come impostarlo:

1. Aprite Keychain Access

   1. Clicca Command + Space per aprire la barra di ricerca
   2. Cerca Keychain Access
   3. Clicca sul Keychain Access app

2. Seleziona la login categoria e clicca sul My Certificates tasto

3. Cerca il tuo certificato nella lista

   Il certificato dovrebbe essere denominato Apple Distribution: [Your Name/Company] (your team ID)

4. Clicca con il pulsante destro sul certificato e seleziona Export

5. Salva il certificato come un .p12 file

   Attenzione

   Questo DEVE ESSERE SALVATO - ne avrai bisogno in seguito

   1. Assicurati di selezionare un nome adatto per il file del certificato
   2. Assicurati che il formato del file sia impostato su Personal Information Exchange (.p12)
   3. Clicca sul Save botton

   

6. Quando ti viene chiesto la password, puoi scegliere:

   • Saltare la password (consigliato per semplicità): Clicca OK senza inserire una password
   • Impostare una password: Se preferisci proteggere il tuo certificato con una password, puoi impostarla qui. I file protetti da password sono pienamente supportati dal __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - basta fornire la password utilizzando l' .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password DIALOGO DI SALVATAGGIO DELLA PASSWORD DEL CERTIFICATO DI ACCESSO ALLA CHIAVE

   

7. Inserisci la password che utilizzi per accedere al tuo Mac. Poi, clicca sul

   bottono. Allow DIALOGO DI SALVATAGGIO DELLA PASSWORD DELLA CHIAVE DI ACCESSO AL LOGIN DEL CERTIFICATO

   

Congratulazioni 🎉 Hai esportato il certificato.

Profilo di provisioning

Ora, sei pronto ad esportare il profilo di provisioning. Ti prometto, questo è l'ultimo cosa dovrai ottenere da Apple.

1. Vai a Profili dello Sviluppatore Apple

2. Seleziona l'equipe corretta dal menu a discesa

   1. Clicca sul tuo nome nell'angolo in alto a destra
   2. Clicca sull'equipe che vuoi utilizzare

3. Assicurati di essere sulla pagina corretta Dovrebbe avere questo aspetto, se non è così clicca su profiles nel pannello laterale

   

4. Clicca sul + bottoni

5. Seleziona il tipo di profilo Seleziona App Store Connect e clicca sul Continue bottoni

   

6. Seleziona l'app che vuoi costruire

   Trova l'app nel menu a discesa e clicca sul Continue bottoni

   

7. Seleziona il certificato di distribuzione corretto

   Seleziona il certificato che hai esportato nel passaggio precedente e clicca sul Continue tasto

   

   Se non sei sicuro del certificato da selezionare, torna a Keychain Access e trova il certificato che hai esportato. Poi controlla la data di scadenza.

   

8. Nome il profilo

   Dai un nome al profilo e clicca sul Generate tasto

   Consiglio

   Il nome del profilo viene estratto automaticamente dal Capgo CLI — non è necessario ricordarlo.

   

9. Scarica il profilo

   Clicca sul Download tasto per scaricare il profilo

   Attenzione

   Questo file DEVE ESSERE SALVATO - ne avrai bisogno in seguito

   

Congratulazioni 🎉 Ora hai tutto ciò di cui hai bisogno per configurare Capgo Build Nativo.

Attenzione

Non commettere mai le credenziali appena create nel tuo repository. Mantienile al sicuro! 🔒

Eseguire il comando di configurazione

Hai fatto! Hai ora tutto il necessario per configurare Capgo Native Build.

Il comando che dovrai eseguire è:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

Sostituisci i valori dei placeholder

Sostituisci i valori dei placeholder sopra con le tue credenziali reali raccolte nei passaggi precedenti:

• --apple-team-id: ID del tuo team Apple
• --apple-key: Percorso del tuo file scaricato .p8 : Il tuo ID chiave Apple
• --apple-key-id: Il tuo ID emittente Apple
• --apple-issuer-id: Percorso del tuo file esportato
• --certificate: Percorso del tuo file scaricato (ID bundle auto-inferito per profili singoli) .p12 : Se tutto è andato bene, vedrai l'output seguente:
• --ios-provisioning-profile: output di salvataggio delle credenziali __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ .mobileprovision : Configurazione CI/CD (__CAPGO_KEEP_0__ Actions)

: Sezione intitolata “Configurazione CI/CD (__CAPGO_KEEP_0__ Actions)”

CI/CD setup (GitHub Actions)

If hai già completato ID del team, chiave Apple, ID chiave Apple e ID rilasciatore Apple, Certificato, e Profilo di provisioning, hai già tutto ciò che ti serve per CI/CD. Questa sezione copre solo come passare quei valori come segreti e variabili di ambiente GitHub delle azioni.

1) Converti i file di credenziali in una riga base64 singola

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

Tip

I segreti GitHub dovrebbero essere valori a riga singola. tr -d '\n' rimuove i ritorni a capo dall'output base64.

2) Crea segreti del repository

In GitHub > Repository > Settings > Secrets and variables > Actionsaggiungi:

Nome segreto	Valore
CAPGO_TOKEN	Il tuo Capgo API token
APP_STORE_CONNECT_TEAM_ID	ID del team da ID del team
APPLE_KEY_ID	Chiave ID da Chiave Apple, ID chiave Apple e ID rilasciatore Apple
APPLE_ISSUER_ID	ID rilasciatore da Chiave Apple, ID chiave Apple e ID rilasciatore Apple
BUILD_CERTIFICATE_BASE64	Contenuto di certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Generato da CLI — copia da .capgo-credentials file
APPLE_KEY_CONTENT	Contenuto di apple_key_base64.txt
P12_PASSWORD (facoltativo)	Il tuo .p12 password se impostato durante l'esportazione

3) Utilizza variabili di ambiente nel tuo GitHub workflow di Actions

github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

Suggerimento

Con questo setup, il CI invia le credenziali solo attraverso le variabili di ambiente. Non è necessario commitare i file di firma o caricarli come artefatti del workflow.

Eseguire la costruzione

Ora sei pronto per eseguire la tua prima costruzione.

Esegui il seguente comando per costruire la tua app:

bunx @capgo/cli@latest build request --platform ios

Congratulazioni 🎉 Hai completato con successo la tua app e ora è pronta per essere pubblicata sul App Store.

Modalità di distribuzione Ad-Hoc

Di default, Capgo costruisce app iOS per la distribuzione sul App Store (TestFlight + App Store). Se hai bisogno di costruire app ad-hoc (per test interni o raccolta di artefatti di CI), puoi utilizzare il --ios-distribution flag.

Nota

La distribuzione ad-hoc non è la stessa della distribuzione Enterprise (In-House). La distribuzione Enterprise richiede un account separato di sviluppatore Apple Enterprise e utilizza profili di provisioning diversi. Capgo supporta attualmente app_store e ad_hoc modalità solo.

When utilizzare il modo ad-hoc

• Desideri distribuire le IPA direttamente ai dispositivi registrati (nessun TestFlight)
• Non hai o non desideri utilizzare una chiave App Store Connect API
• Desideri raccogliere gli artefatti di costruzione via --output-upload senza sottoporre a revisione l'App Store

Requisiti

I costruzioni ad-hoc hanno poche richieste rispetto ai costruzioni per l'App Store:

Autenticazione	Richiesto?
Distribuzione del certificato (.p12)	Sì
Profilo di provisioning ad-hoc (.mobileprovision)	Sì
ID del team (--apple-team-id)	Sì
Chiave di accesso a App Store Connect API (.p8)	No
ID chiave di Apple / ID emittente	No

Nota

In ad_hoc modalità, --apple-key, --apple-key-id, e --apple-issuer-id non sono supportati e vengono ignorati. Questo è il motivo per cui le due righe di App Store Connect sopra non mostrano flag ad-hoc CLI; queste opzioni si applicano solo alla app_store modalità.

Attenzione

Senza una chiave App Store Connect API, il numero di build auto-incrementa utilizza un fallback basato su timestamp. Per sopprimere il warning, passa --skip-build-number-bump.

La creazione di un profilo di provisioning ad-hoc

Segui gli stessi passaggi come Profilo di provisioningma nel passo 5, seleziona Ad Hoc invece di App Store:

1. Vai a Profili di sviluppatore Apple
2. Clicca il + tasto
3. Seleziona Ad Hoc e clicca Continua
4. Scegli la tua app e il certificato di distribuzione
5. Scegli i dispositivi che vuoi registrare
6. Nome e download del profilo

Salvataggio delle credenziali ad-hoc

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

No --apple-key, --apple-key-id, o --apple-issuer-id necessario.

Esecuzione di un build ad-hoc

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

Per raccogliere l'IPA come artefatto di build, aggiungi --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD con build ad-hoc

Per GitHub Actions, hai bisogno di meno segreti rispetto alle build per l'App Store:

.github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

Suggerimento

Nota che APPLE_KEY_ID, APPLE_ISSUER_IDe APPLE_KEY_CONTENT non sono necessari per le costruzioni ad-hoc.

Applicazioni con Estensioni (Multi-Target Signing)

Se la tua app include estensioni (estensioni di condivisione, widget, estensioni di servizio di notifica, ecc.), ogni target di estensione necessita di un proprio profilo di provisioning. Capgo supporta questo tramite la flag ripetibile. --ios-provisioning-profile Esempio: App + Estensione di condivisione

Sezione intitolata “Esempio: App + Estensione di condivisione”

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Each --ios-provisioning-profile mappa le flag a un ID di bundle e il suo file di provisioning. Il CLI:

1. Legge ogni file mobileprovision
2. Estrae automaticamente il nome del profilo dal plist incorporato
3. Codifica in Base64 il file
4. Memorizza tutto come un singolo CAPGO_IOS_PROVISIONING_MAP credenziale

Suggerimento

Hai bisogno di un solo certificato di distribuzione per tutti gli obiettivi — differiscono solo i profili di provisioning per obiettivo.

Migrazione da Profilo Singolo

Se hai utilizzato precedentemente BUILD_PROVISION_PROFILE_BASE64 (singola profilo), esegui:

bunx @capgo/cli@latest build credentials migrate --platform ios

Ciò converte le tue credenziali esistenti di singola profilo nel nuovo formato e elimina le chiavi legacy ( CAPGO_IOS_PROVISIONING_MAP Dopo la migrazione, aggiungi profili di estensione con il comando (incorporamento aggiuntivo):BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Finestra del terminale update Copia nel portapenna

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

protectedTokens

protectedTokens update (non save) per aggiungere profili a credenziali esistenti. Il update comando combina nuovi profili con quelli esistenti. Utilizzare save solo quando si configurano tutte le credenziali da zero.

Risoluzione dei problemi

Il profilo di provisioning non include la capacità XYZ.

A volte, potresti vedere l'errore seguente:

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

Ciò accade perché hai abilitato una nuova capacità dopo la creazione del profilo di provisioning. Il vecchio profilo di provisioning non include ancora la nuova capacità.

Per risolvere questo problema, è necessario rigenerare il profilo di provisioning.

1. Apri Portale dello sviluppatore Apple
2. Seleziona il team corretto dal menu a discesa
3. Clicca sul Profiles tasto
4. Trova il profilo di provisioning che vuoi rigenerare
5. Clicca sul Edit tasto
6. Clickare sul Save tasto
7. Clickare sul Download tasto
8. Riecco il comando di configurazione del setup nativo Capgo con il profilo appena scaricato.

Questo dovrebbe risolvere il problema.

Altri problemi

In caso di problemi con Capgo Native Build, la configurazione delle credenziali o la compilazione dell'app, non esitare a contattarci tramite supporto.

Continua dal build iOS

Se stai utilizzando Build iOS per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Build nativi per il flusso di lavoro del prodotto in Capgo Build nativi, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Azioni di Integrazione per i dettagli di implementazione in GitHub Azioni di Integrazione.