Build iOS

Fai la build e invia app iOS su TestFlight e sull'App Store usando l'infrastruttura Mac dedicata di Capgo.

Cosa imparerai

• Imparerai come fare l'upload della tua app tramite Capgo Native Build
• Imparerai a configurare i certificati per Capgo Native Build

Prerequisiti

• Un account Capgo (basta una prova gratuita per iniziare)
• La tua app è già registrata in Capgo (esegui bunx @capgo/cli@latest app add se non lo hai)
• Nessun Mac richiesto: Capgo Build compila e firma la tua app iOS nel cloud, quindi puoi eseguirlo da macOS, Windows o Linux
• Account Apple Developer valido (99 $/anno) (Devi avere i diritti di admin o owner sull'account Apple Developer)
• La tua app deve essere compilata con successo (localmente in Xcode o con Capgo Build)
• Un'app Capacitor
• Un'icona configurata per l'app. Le app senza icona non possono essere caricate sull'App Store.

Nota

Userò la seguente app per il tutorial: https://github.com/Cap-go/capgo-native-build-tutorial-app

Prima di iniziare nei portali Apple

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

• Attiva l'autenticazione a due fattori per l'Apple Account usato per l'iscrizione
• Scegli il tipo di membership corretto:
  • Persona fisica / Ditta individuale: il tuo nome legale diventerà il nome del venditore sull'App Store
  • Organizzazione: richiede una persona giuridica, un numero D-U-N-S, un sito web aziendale pubblico, un'email di lavoro sul dominio aziendale e una persona autorizzata a vincolare l'organizzazione agli accordi Apple
• Usa un account con accesso sia ad Apple Developer che ad App Store Connect per certificati, record dell'app, chiavi API e TestFlight
• Definisci subito il bundle ID finale. Cambiarlo in seguito significa solitamente dover rifare tutta la configurazione su App Store
• Pianifica questi elementi su App Store Connect prima dell'App Review: URL di supporto, URL della privacy policy, classificazione per età, screenshot, conformità all'esportazione e contatti per l'App Review

Nota

Riferimenti ufficiali utili:

• Diventa membro dell'Apple Developer Program
• Invia le tue app e i tuoi giochi
• Informazioni sulla versione della piattaforma in App Store Connect

Attenzione

Apple aggiorna regolarmente il requisito minimo di SDK. Ad oggi, 28 aprile 2026, le app per iPhone e iPad caricate su App Store Connect devono essere buildate con iOS & iPadOS 26 SDK o versioni successive.

Consigliato: onboarding automatizzato

Non devi fare nulla di tutto questo a mano. L'onboarding di Capgo crea e configura per te le credenziali di firma iOS (certificato di distribuzione + provisioning profile) — questo è il percorso consigliato:

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

La guida manuale qui sotto è solo per chi preferisce configurare le credenziali da solo o vuole capire esattamente cosa fa Capgo sotto il cofano.

La prima build manuale

Prima di iniziare a pensare alla build dell'app con Capgo, dovremmo prima configurarla ed eseguire una prima build per TestFlight manualmente. Ci sono alcuni vantaggi nel fare prima una build manuale:

• Configurerai il certificato di distribuzione sul tuo computer locale
• Creerai il record su App Store se non l'hai ancora fatto
• Potrai individuare eventuali problemi nel processo di build legati alla tua app code

Prima di iniziare, devi avere il certificato di distribuzione installato sul tuo computer locale. È piuttosto complesso, ma lo spiegherò qui sotto.

Configurazione del certificato di distribuzione

1. Apri Xcode

2. Clicca su Xcode -> Settings... In alternativa, puoi usare la scorciatoia Cmd + ,

   

3. Vai su Accounts

4. Trova l'Apple Account aggiunto all'Apple Developer Account

5. Trova il team che userai per distribuire l'app

6. Clicca sul Manage Certificates... pulsante

7. Assicurati che il certificato di distribuzione sia visibile nell'elenco

8. In caso contrario, dovrai creare un nuovo certificato

   Nota

   Apple limita il numero di certificati di distribuzione a 3. Se ne hai più di 3, dovrai eliminarne uno per crearne uno nuovo. Non approfondiremo questo passaggio nel tutorial.

   1. Clicca sul + pulsante e poi su Apple Distribution
   2. Il certificato verrà creato automaticamente. Potrai vederlo nell'elenco. Controlla il passaggio precedente per confermare la sua presenza.

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

Build manuale per TestFlight

1. Apri l'app in Xcode

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

2. Trova e fai clic su archive pulsante

   Nella barra degli strumenti di Xcode, trova e fai clic su product -> archive pulsante.

   

3. Attendi il completamento della build

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

   Compila i seguenti campi:

   1. Nome: il nome della tua app - visibile nell'App Store
   2. SKU - lo SKU della tua app - viene utilizzato per identificare la tua app nell'App Store
   3. Lingua principale - la lingua principale della tua app

   Poi, clicca su next pulsante

   

7. Se la creazione del record dell'app fallisce, chiudi la finestra e riprova ad archiviare l'app.

8. Attendi il completamento dell'upload

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

10. Clicca sul Done pulsante

Potresti pensare che sia tutto a posto e che l'app sia già visibile su TestFlight, ma ci sono ancora alcune cose da completare:

1. Aggiungi te stesso a TestFlight
2. Completa la conformità all'esportazione per rendere il build testabile
3. Compila i metadati obbligatori di App Store Connect, come URL di supporto, URL della privacy policy e classificazione per età
4. Prepara screenshot coerenti con i dispositivi che supporti effettivamente
5. Aggiungi i contatti per la revisione dell'app e le credenziali di test prima dell'invio in produzione

Cominciamo dal primo punto:

Aggiungerti a TestFlight

1. Vai a App Store Connect pagina

2. Accedi con il tuo account Apple Developer

3. Seleziona il team che hai usato per creare il record dell'app. Se fai parte di un solo account developer, puoi saltare questo passaggio.

4. Clicca sul Apps pulsante

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

6. Clicca sul TestFlight pulsante

7. Clicca sul Internal Testers plus pulsante

8. Crea un nuovo gruppo

   Mi piace chiamare il gruppo “internal”. Puoi dargli il nome che preferisci.

   

9. Clicca su Invite testers pulsante

10. Aggiungi te stesso al gruppo

    Trova il tuo nome nell'elenco e seleziona la casella accanto ad esso. (Potrebbe essere necessario aggiornare la pagina per vederti) Quindi, clicca su Add pulsante.

    

11. Verifica di essere stato aggiunto al gruppo

    Ora dovresti vederti nel gruppo.

    

Congratulazioni 🎉 Ti sei aggiunto a TestFlight. Ora c'è solo un'altra cosa da fare prima di poter configurare Capgo Native Build.

Configurazione delle informazioni di conformità

Ora devi garantire ad Apple che la tua app non utilizzi crittografia non standard (come un algoritmo personalizzato). Se la tua app utilizza una crittografia non standard, ti consiglio di leggere la documentazione Apple su come gestire questa situazione. Ci sono due modi per farlo:

1. Puoi farlo manualmente ogni volta che compili la tua app.
2. Puoi configurare il file plist per impostare automaticamente questo valore su false.

Cominciamo dal primo punto:

1. Segui tutti i passaggi 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 fai clic su Manage

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

   Per me, questa è none, ma potrebbe essere diversa per te. Dopo, clicca su Salva

   

5. La tua app dovrebbe ora mostrare ready to test

   

Per il secondo, ecco i passaggi:

1. Apri la Info.plist file

2. Aggiungi la seguente chiave:

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

3. Salva il file

Nota

Qui trovi la documentazione ufficiale Apple su come comunicare ad Apple la tua conformità alle normative sull'esportazione della crittografia.

Installare l'app TestFlight e accettare l'invito

Now, you are QUASI pronto per testare la tua app in TestFlight. Prima, devi completare questi passaggi:

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

Salterò i dettagli su come installare l'app TestFlight sul tuo dispositivo. Se non sei sicuro di come installare un'app, su Google trovi ottime guide.

Per accettare l'invito, riceverai un'email da Apple con un link per accettarlo.

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

2. Clicca su View in TestFlight pulsante

3. Clicca sul Install pulsante

4. Installa l'app sul tuo dispositivo

   Se hai installato l'app in precedenza con Xcode, potresti vedere la schermata seguente. Clicca su install pulsante.

5. Attendi l'installazione dell'app

6. Clicca sul Open e premi il pulsante

Congratulazioni 🎉 Hai accettato l'invito per testare la tua app su TestFlight. Ora puoi configurare Capgo Native Build per compilare e inviare la tua app su TestFlight.

Configurazione di Capgo Native Build

Ci sono alcune cose da configurare in Capgo Native Build per poter compilare e inviare la tua app su TestFlight. Ecco l'elenco di ciò che passerai a Capgo CLI:

Parametro	Descrizione
--platform	La piattaforma per la build (ios)
--apple-team-id	Il tuo Apple Developer Team ID (trovato in Portale Apple Developer)
--apple-key	Percorso del file API Key di App Store Connect (.p8 file)
--apple-key-id	Key ID della tua API Key di App Store Connect
--apple-issuer-id	Il tuo App Store Connect Issuer ID
--certificate	Percorso del certificato di distribuzione (.p12 file)
--ios-provisioning-profile	Mappatura dei provisioning profile (bundleId=path o solo il percorso per un singolo profilo)

Comando di esempio:

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

Partiamo dal Team ID. Trovarlo è piuttosto semplice.

1. Vai su Account Apple Developer e scorri verso il basso

2. Trova il Team ID

   

Chiave Apple, Apple key ID e Apple issuer ID

Ora passiamo alla chiave Apple.

macOS: lascia che Capgo crei questa chiave per te

Su macOS, capgo build init può creare questa chiave API di App Store Connect per te. Scegli “No — creane una per me” e si apre una finestra guidata che avvia App Store Connect, ti accompagna in ogni passaggio e cattura automaticamente la chiave, Key ID e Issuer ID — senza copia-incolla. I passaggi manuali qui sotto sono l'alternativa (e il percorso su Windows o Linux).

1. Vai su Pagina utente e accesso di App Store Connect

   Nota

   A volte il link non funziona. Se non funziona per te, ricarica la pagina.

2. Seleziona il team corretto dal menu a tendina

   1. Clicca sul tuo nome in alto a destra
   2. Clicca sul team che vuoi utilizzare

3. Clicca sul Integrations pulsante

4. Trova il issuer

   Attenzione

   Questo DEVE ESSERE SALVATO - ti servirà più tardi

   Clicca sul copy pulsante per copiare l'issuer

5. Clicca sul pulsante +

6. Imposta il nome della chiave e imposta l'accesso a App manager e clicca sulla Generate pulsante

7. Salva il Key ID

   Attenzione

   Questo DEVE ESSERE SALVATO - ti servirà più tardi

   

8. Scarica la chiave

   Attenzione

   Questo DEVE ESSERE SALVATO - ti servirà più tardi

   Pericolo

   NON CONDIVIDERE MAI LA CHIAVE CON NESSUNO - USALA SOLO NELL'CAPGO CLI

   

   

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

Certificato

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

Tuttavia, Apple, nella sua infinita saggezza, ha deciso che il modo in cui esporti il certificato è piuttosto diverso da quello in cui lo crei 🙃 Vediamo come configurarlo:

1. Apri Accesso Keychain

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

2. Seleziona la login categoria e fai clic su My Certificates pulsante

3. Trova il certificato nell'elenco

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

4. Fai clic destro sul certificato e seleziona Export

5. Salva il certificato come .p12 file

   Attenzione

   Questo DEVE ESSERE SALVATO - ti servirà più tardi

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

   

6. Quando viene richiesta la password, puoi:

   • Salta la password (consigliato per semplicità): clicca OK senza inserire alcuna password
   • Imposta una password: se preferisci proteggere il certificato con una password, puoi impostarla qui. I file .p12 protetti da password sono pienamente supportati da Capgo CLI - basta fornire la password tramite l' --p12-password opzione quando esegui il comando di configurazione.

   

7. Quando viene richiesta la “login keychain password”, inserisci la password che usi per accedere al tuo Mac

   Inserisci la password che usi per accedere al tuo Mac. Poi clicca sul Allow pulsante.

   

Congratulazioni 🎉 Hai esportato il certificato.

Profilo di provisioning

Ora sei pronto a esportare il provisioning profile. Prometto, è l'ultima cosa che dovrai recuperare da Apple.

1. Vai su Profili Apple Developer

2. Seleziona il team corretto dal menu a tendina

   1. Clicca sul tuo nome in alto a destra
   2. Clicca sul team che vuoi utilizzare

3. Assicurati di essere sulla pagina corretta Dovrebbe apparire così; se non è così, clicca su profiles nella sidebar

   

4. Clicca sul + pulsante

5. Seleziona il tipo di profilo Seleziona App Store Connect e clicca sulla Continue pulsante

   

6. Seleziona l'app che vuoi buildare

   Trova la tua app nel menu a tendina e clicca su Continue pulsante

   

7. Seleziona il certificato di distribuzione corretto

   Seleziona il certificato esportato nel passaggio precedente e clicca su Continue pulsante

   

   Se non sei sicuro di quale certificato selezionare, torna in Accesso Portachiavi e trova il certificato che hai esportato. Poi controlla la data di scadenza.

   

8. Dai un nome al profilo

   Dai un nome al profilo e clicca su Generate pulsante

   Tip

   Il nome del profilo viene estratto automaticamente da Capgo CLI — non devi ricordarlo.

   

9. Scarica il profilo

   Clicca sul Download pulsante per scaricare il profilo

   Attenzione

   Questo file DEVE ESSERE SALVATO - ti servirà più tardi

   

Congratulazioni 🎉 Ora hai tutto ciò che ti serve per configurare Capgo Native Build.

Attenzione

Non committare mai le credenziali appena create nel tuo repository. Tienile al sicuro! 🔒

Esecuzione del comando di configurazione

Ce l'hai fatta! Ora hai tutto il necessario per configurare Capgo Native Build.

The command you will need to run is:

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 segnaposto

Sostituisci i valori segnaposto sopra con le tue credenziali effettive raccolte nei passaggi precedenti:

• --apple-team-id: Il tuo Apple Team ID
• --apple-key: Percorso del file scaricato .p8 chiave
• --apple-key-id: Apple Key ID
• --apple-issuer-id: Apple Issuer ID
• --certificate: Percorso del file .p12 certificato
• --ios-provisioning-profile: Percorso del file scaricato .mobileprovision esportato (bundle ID dedotto automaticamente per profili singoli)

Se tutto è andato a buon fine, vedrai l'output seguente:

Apple auth failed? Sync your clock

Se la chiave API di App Store Connect sembra corretta ma l'autenticazione continua a fallire, sincronizza l'orologio del computer e riprova. Capgo firma il JWT di Apple con l'ora del tuo sistema locale, e Apple rifiuta i token che scadono più di 20 minuti nel futuro. Basta un orologio disallineato di pochi secondi per far fallire questo passaggio.

Guarda il guida al troubleshooting del builder per i passaggi sulla sincronizzazione dell'orologio.

Configurazione CI/CD (GitHub Actions)

Se hai già completato ID del Team, Chiave Apple, Apple key ID e Apple issuer ID, Certificato, e Profilo di provisioning, hai già tutto il necessario per la CI/CD. Questa sezione spiega solo come passare quei valori come secret delle GitHub Actions e variabili d'ambiente.

1) Converti i file delle credenziali in base64 su una riga

# 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 devono essere su una singola riga. tr -d '\n' rimuove le interruzioni di riga dall'output base64.

2) Crea i secret del repository

In GitHub > Repository > Settings > Secrets and variables > Actions, aggiungi:

Nome del secret	Valore
CAPGO_TOKEN	Il tuo token Capgo API
APP_STORE_CONNECT_TEAM_ID	Team ID da ID del Team
APPLE_KEY_ID	Key ID da Chiave Apple, Apple key ID e Apple issuer ID
APPLE_ISSUER_ID	Issuer ID da Chiave Apple, Apple key ID e Apple issuer ID
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 (opzionale)	Il tuo .p12 password, se impostata durante l'export

3) Usa le variabili d'ambiente nel tuo workflow GitHub 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 }}

Tip

Con questa configurazione, la CI invia le credenziali solo tramite variabili d'ambiente. Non è necessario committare i file di firma o caricarli come artifact del workflow.

Esecuzione della build

Ora sei pronto per la tua prima build.

Esegui il seguente comando per buildare la tua app:

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

Congratulazioni 🎉 A questo punto hai buildato con successo la tua app ed è pronta per essere inviata all'App Store.

Invia per la revisione dell'App Store

Il normale flusso di build per l'App Store carica il build su App Store Connect/TestFlight. Se il tuo rilascio CI deve anche allegare il build TestFlight elaborato alla versione dell'App Store e inviarlo alla App Review, passa --submit-to-store-review con un build di release:

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 "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales" \
  --no-ios-automatic-release

Questo richiede le credenziali della chiave API di App Store Connect (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, e APP_STORE_CONNECT_TEAM_ID). Caricamenti e password specifiche per l'app ad_hoc distribuzione non possono inviare una build per la revisione. --store-release-name è la versione di App Store; se omessa, Capgo legge MARKETING_VERSION dal progetto Xcode. --store-release-notes è il testo di fallback per le novità di App Store, e ogni --store-release-notes-locale "locale=notes" voce può sovrascriverlo per una localizzazione dello store. Usa --ios-automatic-release per pubblicare automaticamente dopo l'approvazione di Apple, oppure --no-ios-automatic-release per attendere una pubblicazione manuale. --ios-testflight-groups è ancora disponibile per la distribuzione beta esterna, ma non è richiesto per l'invio in revisione su App Store.

Modalità di distribuzione Ad-Hoc

Di default, Capgo compila le app iOS per la distribuzione su App Store (TestFlight + App Store). Se invece hai bisogno di build ad-hoc (per test interni o raccolta di artefatti CI), puoi usare il --ios-distribution flag.

Nota

La distribuzione ad-hoc è hai identica a quella Enterprise (In-House). La distribuzione Enterprise richiede un account Apple Developer Enterprise separato e utilizza profili di provisioning diversi. Capgo supporta attualmente solo app_store e ad_hoc modalità.

Quando usare la modalità ad-hoc

• Vuoi distribuire IPAs direttamente a dispositivi registrati (senza TestFlight)
• Non hai o non vuoi usare una chiave API di App Store Connect
• Vuoi raccogliere gli artefatti di build tramite --output-upload senza sottometterli all'App Store

Requisiti

Le build ad-hoc hanno meno requisiti rispetto alle build per l'App Store:

Credenziale	Obbligatorio?
Certificato di distribuzione (.p12)	Sì
Provisioning profile Ad-hoc (.mobileprovision)	Sì
Team ID (--apple-team-id)	Sì
Chiave API di App Store Connect (.p8)	No
Apple Key ID / Issuer ID	No

Nota

In ad_hoc mode, --apple-key, --apple-key-id, e --apple-issuer-id are not supported and are ignored. This is why the two App Store Connect rows above do not show ad-hoc CLI flags; these options apply to app_store solo in modalità

Attenzione

Senza una chiave API di App Store Connect, l'incremento automatico del numero di build usa un fallback basato su timestamp. Per disattivare l'avviso, passa --skip-build-number-bump.

Creazione di un profilo di provisioning ad-hoc

Segui gli stessi passaggi di Profilo di provisioning, ma al passaggio 5, seleziona Ad Hoc invece di App Store:

1. Vai su Profili Apple Developer
2. Clicca sul + pulsante
3. Seleziona Ad Hoc e clicca su Continua
4. Seleziona l'app e il certificato di distribuzione
5. Seleziona i dispositivi da registrare
6. Dai un nome e scarica il profilo

Salvataggio 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 una build ad-hoc

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

Per ottenere l'IPA come artifact 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 le GitHub Actions, servono meno secret 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

Tip

Nota che APPLE_KEY_ID, APPLE_ISSUER_ID, e APPLE_KEY_CONTENT non sono necessari per le build ad-hoc.

App con estensioni (Multi-Target Signing)

Se la tua app include estensioni (share extensions, widget, notification service extensions, ecc.), ogni target di estensione richiede il proprio provisioning profile. Capgo supporta questa funzionalità tramite il ripetibile --ios-provisioning-profile flag.

Esempio: App + Share Extension

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"

Ogni --ios-provisioning-profile flag associa un bundle ID al file del provisioning profile. Il CLI:

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

Tip

Serve un certificato di distribuzione per tutti i target: solo i profili di provisioning variano per target.

Migrazione da Single Profile

Se in precedenza usavi BUILD_PROVISION_PROFILE_BASE64 (single profile), esegui:

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

Questo converte le tue credenziali esistenti a profilo singolo nel nuovo CAPGO_IOS_PROVISIONING_MAP formato e rimuove le chiavi legacy (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Dopo la migrazione, aggiungi i profili di estensione con il update comando (merge additivo):

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

Tip

Usa update (non save) per aggiungere profili alle credenziali esistenti. Il update comando unisce i nuovi profili con quelli esistenti. Usa save solo quando configuri tutte le credenziali da zero.

Risoluzione problemi

Il provisioning profile non include la capacità XYZ.

A volte potresti vedere il seguente errore:

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

Questo accade perché hai abilitato una nuova capacità dopo la creazione del provisioning profile. Il vecchio provisioning profile non include ancora la nuova capacità.

Per risolvere, devi rigenerare il provisioning profile.

1. Apri Portale Apple Developer
2. Seleziona il team corretto dal menu a tendina
3. Clicca sul Profiles pulsante
4. Trova il provisioning profile da rigenerare
5. Clicca sul Edit pulsante
6. Clicca sul Save pulsante
7. Clicca sul Download pulsante
8. Riesegui il comando di configurazione Capgo Native Build con il profilo appena scaricato.

Questo dovrebbe risolvere il problema.

Altri problemi

Se per qualsiasi motivo stai riscontrando problemi con Capgo Native Build, nella configurazione delle credenziali o nella build dell'app, non esitare a contattarci tramite il nostro supporto.

Continua dalle build iOS

Se stai usando Build iOS per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli implementativi in CI/CD Integration, e Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration.