Caricare build iOS su TestFlight con Devin

Devin può archiviare un’app iOS, firmarla, caricarla su TestFlight e aggiungere la build a un beta group. Esegue xcodebuild su una VM macOS e si autentica con una API key di App Store Connect che memorizzi come secrets di Devin. Prima che Devin possa caricare una build, devi:

Configurare la tua app in App Store Connect.
Creare una API key di App Store Connect.
Aggiungere la key e il tuo Team ID a Devin come secrets.
Assicurarti che Devin possa raggiungere i server di Apple.

Il caricamento su TestFlight richiede sessioni macOS. Se utilizzi una distribuzione Dedicated SaaS, contatta il tuo account team per abilitare le VM macOS.

Requisiti

Requisito	Dettaglio
Iscrizione all’Apple Developer Program	Un’iscrizione a pagamento per il team proprietario dell’app.
Record dell’app in App Store Connect	Un’app con lo stesso bundle ID del progetto Xcode.
API key di App Store Connect	Una chiave del team con il ruolo App Manager.
Secrets di Devin	`ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY` e `APPLE_TEAM_ID`.
Accesso alla rete	La VM macOS di Devin deve poter raggiungere i server Apple.

Configurare App Store Connect

Esegui questi passaggi nel portale Apple Developer e in App Store Connect. Devin non può eseguirli al posto tuo: la maggior parte richiede un Account Holder o un Admin e alcuni richiedono l’autenticazione a due fattori sull’Apple Account di una persona.

Accetta i contratti più recenti

L’Account Holder accede a App Store Connect e accetta eventuali contratti in sospeso nella sezione Business. Gli upload non riescono finché un contratto richiesto resta in sospeso.

Registra il bundle ID

Nel portale Apple Developer, vai su Certificates, Identifiers & Profiles → Identifiers e registra un App ID corrispondente al bundle ID del target della tua app. Salta questo passaggio se l’identificatore esiste già.

Crea il record dell'app

In App Store Connect, vai su Apps, fai clic su + e seleziona New App. Scegli la piattaforma, il nome, la lingua principale, il bundle ID del passaggio precedente e uno SKU. Gli upload su TestFlight non riescono se per quel bundle ID non esiste alcun record dell’app.

Crea un beta group

Apri l’app, vai su TestFlight e crea un gruppo:

Internal testing: i tester devono essere utenti del tuo team di App Store Connect. Le build sono disponibili non appena termina l’elaborazione.
External testing: i tester possono essere chiunque disponga di un indirizzo email o di un collegamento pubblico. Compila prima le Test Information (descrizione della beta app, email per il feedback e contatti per il review). La prima build di ogni versione passa per la Beta App Review.

Rispondi alla conformità all'esportazione

Ogni build deve rispondere alla domanda sulla conformità all’esportazione prima che i tester possano installarla. Per evitare di rispondere alla domanda a ogni build, imposta ITSAppUsesNonExemptEncryption nel file Info.plist della tua app. Impostalo su NO se l’app usa solo crittografia esente, come HTTPS.

Creare una API key di App Store Connect

Devin si autentica con una API key di App Store Connect, non con un Apple Account. La key non richiede l’autenticazione a due fattori.

Abilitare l'accesso alle API

In App Store Connect, vai su Users and Access → Integrations → App Store Connect API. Se l’accesso alle API non è ancora abilitato, l’Account Holder deve fare clic su Request Access e accettare i termini.

Generare una team key

In Team Keys, fai clic su +. Inserisci un nome, ad esempio Devin TestFlight, e seleziona il ruolo App Manager. Per generare una key è necessario il ruolo Admin. Se Xcode non riesce a creare un certificato di distribuzione con una key App Manager, genera una key con il ruolo Admin.

Scaricare la chiave privata

Fai clic su Download accanto alla nuova key per salvare AuthKey_<KEY_ID>.p8. Apple consente di scaricare il file una sola volta: se lo perdi, revoca la key e generane una nuova.

Copiare l'Issuer ID e il Key ID

L’Issuer ID è indicato sopra la tabella delle key, mentre il Key ID si trova nella riga della key.

Trovare il tuo Team ID

Nel portale Apple Developer, vai su Membership details e copia il Team ID: è una stringa di 10 caratteri, ad esempio A1B2C3D4E5.

Chiunque disponga del file .p8 può caricare build e gestire TestFlight per tutte le app del tuo team. Conservalo esclusivamente nei secrets di Devin e non committarlo in un repository.

Aggiungere secrets a Devin

Aggiungi i seguenti valori come secrets non elaborati nella Secrets page:

Nome del secret	Valore	Dove trovarlo
`ASC_KEY_ID`	Key ID, ad esempio `2X9R4HXF34`	App Store Connect → Users and Access → Integrations → App Store Connect API
`ASC_ISSUER_ID`	Issuer ID, un UUID	Stessa pagina, sopra la tabella delle chiavi
`ASC_PRIVATE_KEY`	Contenuto completo di `AuthKey_<KEY_ID>.p8`, incluse le righe `-----BEGIN PRIVATE KEY-----` e `-----END PRIVATE KEY-----`	Il file scaricato al momento della creazione della chiave
`APPLE_TEAM_ID`	Team ID, ad esempio `A1B2C3D4E5`	Portale Apple Developer → Membership details

Per copiare la chiave privata su Mac, esegui:

pbcopy < AuthKey_<KEY_ID>.p8

Scegli un ambito per i secret:

Organization: tutte le sessioni della tua organizzazione possono usare la chiave. Usa questo ambito quando il team rilascia build con Devin.
Personal: solo le sessioni che avvii tu possono usare la chiave.

I secret sono disponibili solo nelle sessioni avviate dopo la loro aggiunta. Per maggiori informazioni sugli ambiti, consulta Secrets.

Consentire l’accesso alla rete

La VM macOS di Devin deve poter raggiungere i server Apple per firmare e caricare le build. Se la tua organizzazione applica una network policy restrittiva, aggiungi api.appstoreconnect.apple.com e gli altri host Apple utilizzati da xcodebuild per la firma e il caricamento. Consentire *.apple.com è sufficiente a coprirli tutti. Un host bloccato si manifesta di solito come un errore di autenticazione, non come un errore di rete. Consulta Risoluzione dei problemi.

Caricare una build

Avvia una sessione macOS e chiedi a Devin di caricare una build:

Archivia lo schema MyApp e caricalo su TestFlight. Usa un numero di build
superiore a quello dell'ultima build su App Store Connect, aggiungi la build al
gruppo "QA" e, al termine, inviami il numero di build.

Devin usa i secret per effettuare le seguenti operazioni:

Scrive ASC_PRIVATE_KEY in ~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8 con autorizzazioni 0600.
Verifica l’ultimo numero di build tramite l’API di App Store Connect e ne sceglie uno superiore.
Archivia l’app con xcodebuild archive.
Firma e carica la build con xcodebuild -exportArchive.
Attende il completamento dell’elaborazione, quindi aggiunge la build al beta group tramite l’API di App Store Connect.

Il passaggio di esportazione usa un plist di opzioni di esportazione con destination impostato su upload:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>method</key><string>app-store-connect</string>
  <key>destination</key><string>upload</string>
  <key>teamID</key><string>A1B2C3D4E5</string>
  <key>signingStyle</key><string>automatic</string>
</dict>
</plist>

E questi comandi:

xcodebuild -project MyApp.xcodeproj -scheme MyApp \
  -configuration Release -destination 'generic/platform=iOS' \
  -archivePath build/MyApp.xcarchive \
  CURRENT_PROJECT_VERSION=<build-number> archive

xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath build/export \
  -allowProvisioningUpdates \
  -authenticationKeyID "$ASC_KEY_ID" \
  -authenticationKeyIssuerID "$ASC_ISSUER_ID" \
  -authenticationKeyPath ~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8

-allowProvisioningUpdates consente a Xcode di creare il certificato di distribuzione e il provisioning profile con l’API key, così la VM non necessita di avere installati gli asset di firma. Se il tuo repository dispone già di uno script di release, come una lane di fastlane o un target make, chiedi a Devin di usarlo. fastlane accetta la stessa key tramite app_store_connect_api_key.

Salva i passaggi nel tuo blueprint

Per evitare di ripetere le istruzioni in ogni prompt, aggiungile alla sezione knowledge del blueprint del tuo repository:

runs-on: macos

knowledge:
  - name: testflight
    contents: |
      To upload a TestFlight build:
      1. Write $ASC_PRIVATE_KEY to ~/.appstoreconnect/private_keys/AuthKey_$ASC_KEY_ID.p8 (chmod 600).
      2. Use a build number higher than the latest build in App Store Connect.
      3. Archive the MyApp scheme, then run xcodebuild -exportArchive with
         ExportOptions.plist (destination: upload, teamID: $APPLE_TEAM_ID),
         -allowProvisioningUpdates, and the -authenticationKey* flags.
      4. Add the build to the "QA" beta group.

Troubleshooting

No Accounts with App Store Connect Access o Failed to Use Accounts durante l’esportazione. Verifica innanzitutto l’accesso alla rete. Se la VM non riesce a raggiungere i server Apple, xcodebuild segnala questo errore anche quando la chiave è valida. Cerca ITunesConnectFoundationErrorDomain Code=-1003 nelle righe precedenti. Se la rete funziona correttamente, verifica che la chiave abbia il ruolo App Manager. No profiles for '<bundle ID>' were found. Il bundle ID non è registrato per il team indicato in APPLE_TEAM_ID, oppure non esiste un record dell’app corrispondente in App Store Connect. The provided entity includes an attribute with a value that has already been used. Il numero di build è già stato usato per questa versione. Ripeti l’upload con un numero di build superiore. La build viene caricata ma i tester non riescono a installarla. Controlla la build in App Store Connect → TestFlight. Potrebbe essere ancora in elaborazione, mancare delle informazioni sulla conformità all’esportazione oppure essere in attesa della Beta App Review. Xcode non riesce a creare un certificato di distribuzione. Il ruolo della chiave non consente di gestire i certificati. Genera una chiave con il ruolo Admin oppure chiedi a un Admin di creare il certificato di distribuzione nel portale Apple Developer. Le variabili d’ambiente sono vuote nella sessione. I secret sono disponibili solo nelle sessioni avviate dopo averli aggiunti. Avvia una nuova sessione.

Introduzione

Guide fondamentali

Introduzione a Devin

Lavorare con Devin

Guide sul prodotto

Integrazioni

Admin

Note di rilascio

Caricare build iOS su TestFlight con Devin

Requisiti

Configurare App Store Connect

Creare una API key di App Store Connect

Aggiungere secrets a Devin

Consentire l’accesso alla rete

Caricare una build

Salva i passaggi nel tuo blueprint

Troubleshooting

​Requisiti

​Configurare App Store Connect

​Creare una API key di App Store Connect

​Aggiungere secrets a Devin

​Consentire l’accesso alla rete

​Caricare una build

​Salva i passaggi nel tuo blueprint

​Troubleshooting

Requisiti

Configurare App Store Connect

Creare una API key di App Store Connect

Aggiungere secrets a Devin

Consentire l’accesso alla rete

Caricare una build

Salva i passaggi nel tuo blueprint

Troubleshooting