Build iOS

Build dan submit aplikasi iOS ke TestFlight dan App Store menggunakan infrastruktur Mac khusus Capgo.

Apa yang akan Anda pelajari

• Anda akan belajar cara upload aplikasi via Capgo Native build
• Anda akan belajar cara mengonfigurasi sertifikat untuk Capgo Native Build

Prerequisites

• Akun Capgo (free trial sudah cukup untuk memulai)
• Aplikasi Anda sudah terdaftar di Capgo (jalankan bunx @capgo/cli@latest app add jika belum)
• Tanpa Mac: Capgo Build meng-compile dan sign aplikasi iOS Anda di cloud, jadi Anda bisa menjalankannya dari macOS, Windows, atau Linux
• Akun Apple Developer yang valid ($99/tahun) (Anda harus punya hak admin atau owner di akun Apple Developer)
• Aplikasi Anda harus berhasil di-build (di Xcode lokal, atau dengan Capgo Build)
• Aplikasi Capacitor
• Ikon aplikasi yang sudah dikonfigurasi. Aplikasi tanpa ikon tidak bisa di-upload ke App Store.

Catatan

Saya akan menggunakan aplikasi berikut untuk tutorial ini: https://github.com/Cap-go/capgo-tutorial-native-build-app

Sebelum memulai di portal Apple

Sebelum Anda mengatur sertifikat atau melakukan upload TestFlight pertama Anda, pastikan akun dan tim Apple sudah siap:

• Aktifkan autentikasi dua faktor untuk Apple Account yang dipakai saat pendaftaran
• Pilih tipe membership yang sesuai:
  • Individu / Pengusaha Perorangan: nama resmi pribadi Anda akan menjadi nama penjual di App Store
  • Organisasi: memerlukan entitas hukum, nomor D-U-N-S, situs web perusahaan yang publik, email kerja di domain perusahaan, dan orang yang berwenang mengikat organisasi ke perjanjian Apple
• Gunakan akun yang bisa mengakses Apple Developer dan App Store Connect untuk sertifikat, record aplikasi, kunci API, dan TestFlight
• Tentukan bundle ID final Anda sejak awal. Mengubahnya nanti biasanya berarti harus mengulang setup App Store
• Siapkan item App Store Connect ini sebelum App Review: URL support, URL kebijakan privasi, rating usia, screenshot, kepatuhan ekspor, dan detail kontak App Review

Catatan

Referensi resmi yang berguna:

• Menjadi anggota Apple Developer Program
• Kirim aplikasi dan game Anda
• Informasi versi platform di App Store Connect

Peringatan

Apple memperbarui persyaratan minimum SDK secara berkala. Per 28 April 2026, aplikasi iPhone dan iPad yang diunggah ke App Store Connect harus dibangun dengan iOS & iPadOS 26 SDK atau versi terbaru.

Direkomendasikan: onboarding otomatis

Anda tidak perlu melakukan ini secara manual. Onboarding Capgo membuat dan mengonfigurasi kredensial signing iOS Anda (distribution certificate + provisioning profile) secara otomatis — ini adalah cara yang direkomendasikan:

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

Panduan manual di bawah ini hanya untuk Anda yang lebih suka mengatur kredensial sendiri, atau ingin memahami persis apa yang dilakukan Capgo di balik layar.

Build manual pertama

Sebelum mulai membangun aplikasi dengan Capgo, kita perlu melakukan setup terlebih dahulu dan membuat build TestFlight pertama secara manual. Ada beberapa keuntungan melakukan build manual di awal:

• Anda akan mengatur distribution certificate di mesin lokal Anda
• Buat record App Store jika Anda belum melakukannya
• Anda akan dapat mendeteksi masalah apa pun pada proses build yang terkait dengan aplikasi code Anda

Sebelum memulai, Anda harus sudah menginstal distribution certificate di mesin lokal. Proses ini cukup kompleks, namun saya akan menjelaskannya di bawah ini.

Menyiapkan distribution certificate

1. Buka Xcode

2. Klik pada Xcode -> Settings... Atau, Anda bisa menggunakan shortcut Cmd + ,

   

3. Buka Accounts

4. Cari Apple Account yang ditambahkan ke Apple Developer Account

5. Cari team yang akan kamu gunakan untuk deploy app

6. Klik pada Manage Certificates... tombol

7. Pastikan Anda dapat melihat distribution certificate di dalam daftar

8. Jika tidak ada, Anda perlu membuat certificate baru

   Catatan

   Apple membatasi jumlah distribution certificate yang bisa Anda miliki maksimal 3. Jika Anda punya lebih dari 3 certificate, Anda perlu menghapus salah satunya untuk membuat certificate baru. Saya tidak akan membahasnya di tutorial ini.

   1. Klik pada + tombol, lalu pada Apple Distribution
   2. Certificate akan dibuat secara otomatis. Anda bisa melihatnya di daftar. Cek langkah sebelumnya untuk memastikannya.

Setelah distribution certificate terpasang, Anda bisa memulai proses build.

Manual build ke TestFlight

1. Buka aplikasi di Xcode

   Jalankan bunx cap open ios untuk membuka aplikasi di Xcode.

2. Temukan dan klik pada archive tombol

   Di toolbar Xcode, cari dan klik product -> archive tombol.

   

3. Tunggu hingga build selesai

4. Klik pada Distribute App tombol

   

5. Pilih TestFlight Internal Only sebagai metode distribusi dan klik Distribute tombol

   

6. Konfigurasikan app record

   Fill in the following fields:

   1. Name: Nama aplikasi Anda - akan muncul di App Store
   2. SKU - SKU aplikasi Anda - digunakan untuk mengidentifikasi aplikasi Anda di App Store
   3. The primary language - bahasa utama aplikasi Anda

   Lalu, klik pada next tombol

   

7. Jika pembuatan app record gagal, coba tutup jendelanya dan coba archive app lagi.

8. Tunggu hingga proses upload selesai

9. Jika semua berjalan lancar, Anda akan melihat layar berikut

10. Klik pada Done tombol

Anda mungkin berpikir semuanya sudah beres dan app sudah bisa dilihat di TestFlight, tapi masih ada beberapa hal yang perlu diselesaikan:

1. Tambahkan diri Anda ke TestFlight
2. Selesaikan export compliance agar build bisa dites
3. Isi metadata App Store Connect yang diperlukan seperti URL dukungan, URL kebijakan privasi, dan rating usia
4. Siapkan screenshot yang sesuai dengan perangkat yang Anda dukung
5. Tambahkan detail kontak App Review dan kredensial pengujian sebelum submit ke produksi

Mari mulai dengan cara pertama:

Menambahkan diri Anda ke TestFlight

1. Buka halaman App Store Connect halaman

2. Masuk dengan akun Apple Developer Anda

3. Pilih tim yang Anda gunakan saat membuat record aplikasi. Jika Anda hanya punya satu akun developer, langkah ini bisa dilewati.

4. Klik pada Apps tombol

5. Cari aplikasi yang Anda buat di langkah sebelumnya lalu klik aplikasi tersebut

6. Klik pada TestFlight tombol

7. Klik pada Internal Testers plus tombol

8. Buat grup baru

   Saya menamai grupnya “internal”. Anda bebas menamainya sesuka hati.

   

9. Klik pada Invite testers tombol

10. Tambahkan diri Anda ke grup

    Cari nama Anda di daftar dan centang kotak di samping nama Anda. (Anda mungkin perlu refresh halaman untuk melihat nama Anda) Lalu, klik pada Add tombol.

    

11. Verifikasi bahwa Anda telah ditambahkan ke grup

    Sekarang, Anda seharusnya sudah muncul di dalam grup.

    

Selamat 🎉 Anda telah menambahkan diri ke TestFlight. Sekarang, hanya ada satu hal lagi yang perlu dilakukan sebelum Anda bisa mengonfigurasi Capgo Native Build.

Mengatur informasi kepatuhan

Sekarang Anda perlu menyatakan ke Apple bahwa aplikasi Anda tidak menggunakan enkripsi non-standar (seperti algoritma kustom). Jika aplikasi Anda menggunakan enkripsi non-standar, saya sarankan membaca dokumentasi Apple cara menanganinya.\nAda dua cara untuk melakukannya:

1. Anda bisa melakukannya secara manual setiap kali melakukan build aplikasi.
2. Anda bisa mengonfigurasi file plist agar secara otomatis mengatur nilai ini ke false.

Mari mulai dengan cara pertama:

1. Ikuti semua langkah dari bagian sebelumnya untuk menemukan bagian TestFlight di App Store Connect

2. Klik pada Builds -> iOS

3. Cari build dengan informasi kepatuhan yang hilang dan klik Manage

4. Pilih opsi yang paling sesuai dengan aplikasi Anda

   Bagi saya, ini adalah none, tapi mungkin berbeda bagi Anda. Setelah itu, klik Save

   

5. Aplikasi Anda sekarang seharusnya bertuliskan ready to test

   

Untuk yang kedua, berikut adalah langkah-langkahnya:

1. Buka Info.plist file

2. Tambahkan key berikut:

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

3. Simpan file

Catatan

Berikut adalah dokumentasi resmi Apple tentang cara memberi tahu Apple mengenai kepatuhan Anda terhadap regulasi ekspor enkripsi.

Menginstal aplikasi TestFlight dan menerima undangan

Sekarang, Anda HAMPIR siap menguji aplikasi Anda di TestFlight. Sebelum itu, Anda perlu melakukan hal berikut:

1. Download the aplikasi TestFlight dari App Store di perangkat iOS/iPadOS Anda
2. Terima undangan untuk mencoba aplikasi Anda

Saya tidak akan membahas detail cara instal aplikasi TestFlight di perangkat Anda. Jika Anda bingung cara instal aplikasi, Google punya banyak panduan bagus untuk melakukannya.

Untuk menerima undangan, Anda akan menerima email dari Apple berisi link untuk menerima undangan tersebut.

1. Buka email dari Apple yang berisi link untuk menerima undangan

2. Klik pada View in TestFlight tombol

3. Klik pada Install tombol

4. Instal aplikasi di perangkat Anda

   Jika sebelumnya Anda sudah menginstal aplikasi menggunakan Xcode, layar berikut mungkin akan muncul. Silakan klik tombol install tombol.

5. Tunggu hingga aplikasi selesai diinstal

6. Klik pada Open dan klik tombol tersebut

Selamat 🎉 Anda telah menerima undangan untuk menguji aplikasi Anda di TestFlight. Sekarang, Anda dapat mengonfigurasi Capgo Native Build untuk melakukan build dan submit aplikasi Anda ke TestFlight.

Konfigurasi Capgo Native Build

Ada beberapa hal yang perlu Anda konfigurasi di Capgo Native Build agar bisa melakukan build dan submit aplikasi Anda ke TestFlight. Berikut adalah daftar hal yang akan Anda masukkan ke Capgo CLI:

Parameter	Deskripsi
--platform	Platform untuk build (ios)
--apple-team-id	Apple Developer Team ID Anda (ditemukan di Portal Apple Developer)
--apple-key	Path ke file API Key App Store Connect Anda (.p8 file)
--apple-key-id	Key ID dari API Key App Store Connect Anda
--apple-issuer-id	App Store Connect Issuer ID Anda
--certificate	Path ke distribution certificate Anda (.p12 file)
--ios-provisioning-profile	Mapping provisioning profile (bundleId=path atau cukup path untuk satu profile)

Contoh command:

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 Tim

Mari mulai dengan team ID. Mencarinya cukup mudah.

1. Buka Akun Apple Developer dan scroll ke bawah

2. Temukan Team ID

   

Apple key, Apple key ID, dan Apple issuer ID

Sekarang, mari lanjut ke kunci Apple.

macOS: biarkan Capgo membuatkan kunci ini untuk Anda

Di macOS, capgo build init bisa membuatkan kunci API App Store Connect ini untuk Anda. Pilih “Tidak — buatkan untuk saya” dan jendela panduan akan membuka App Store Connect, memandu Anda di setiap langkah, serta mengambil kunci, Key ID, dan Issuer ID secara otomatis — tanpa perlu copy-paste. Langkah manual di bawah adalah alternatifnya (dan cara untuk Windows atau Linux).

1. Buka Halaman user dan akses App Store Connect

   Catatan

   Terkadang link tidak berfungsi bagi saya. Muat ulang halaman jika tidak berhasil di tempat Anda.

2. Pilih tim yang sesuai di menu dropdown

   1. Klik nama Anda di pojok kanan atas
   2. Klik tim yang ingin Anda gunakan

3. Klik pada Integrations tombol

4. Temukan issuer

   Peringatan

   Ini HARUS DISIMPAN - Anda akan membutuhkannya nanti

   Klik pada copy tombol untuk menyalin issuer

5. Click on the plus button

6. Set the name of the key and set the access to App manager dan klik pada Generate tombol

7. Simpan key ID

   Peringatan

   Ini HARUS DISIMPAN - Anda akan membutuhkannya nanti

   

8. Unduh kuncinya

   Peringatan

   Ini HARUS DISIMPAN - Anda akan membutuhkannya nanti

   Bahaya

   JANGAN PERNAH BAGIKAN KEY INI KE SIAPAPUN - GUNAKAN HANYA DI CAPGO CLI

   

   

Selamat 🎉 Anda telah membuat Apple key, Apple key ID, dan Apple issuer ID.

Sertifikat

Sekarang, Anda siap mengekspor sertifikat. Seperti yang Anda ingat, salah satu langkah awal panduan ini adalah menyiapkan distribution certificate.

Namun, dalam kebijaksanaannya yang tak terbatas, Apple memutuskan bahwa cara mengekspor sertifikat cukup berbeda dengan cara membuatnya 🙃 Mari kita mulai mengaturnya:

1. Buka Keychain Access

   1. Klik Command + Space untuk membuka search bar
   2. Cari Keychain Access
   3. Klik pada Keychain Access aplikasi

2. Pilih login kategori dan klik pada My Certificates tombol

3. Cari sertifikat Anda di daftar

   Nama sertifikatnya harus Apple Distribution: [Your Name/Company] (your team ID)

4. Klik kanan pada sertifikat dan pilih Export

5. Simpan sertifikat sebagai .p12 file

   Peringatan

   Ini HARUS DISIMPAN - Anda akan membutuhkannya nanti

   1. Pastikan Anda memilih nama yang tepat untuk file sertifikat
   2. Pastikan format file diatur ke Personal Information Exchange (.p12)
   3. Klik pada Save tombol

   

6. Saat diminta kata sandi, Anda bisa:

   • Lewati kata sandi (disarankan agar simpel): Klik OK tanpa memasukkan kata sandi
   • Atur kata sandi: Jika ingin melindungi sertifikat dengan kata sandi, Anda bisa mengaturnya di sini. File yang dilindungi kata sandi .p12 file didukung sepenuhnya oleh Capgo CLI - cukup masukkan kata sandi menggunakan --p12-password opsi saat menjalankan perintah konfigurasi.

   

7. Saat diminta “login keychain password”, masukkan kata sandi yang Anda gunakan untuk login ke Mac Anda

   Masukkan kata sandi yang Anda gunakan untuk login ke Mac Anda. Kemudian, klik pada Allow tombol.

   

Selamat 🎉 Sertifikat berhasil diekspor.

Profil provisioning

Sekarang, Anda siap mengekspor provisioning profile. Saya jamin, ini hal terakhir yang perlu Anda ambil dari Apple.

1. Buka Profil Apple Developer

2. Pilih tim yang sesuai di menu dropdown

   1. Klik nama Anda di pojok kanan atas
   2. Klik tim yang ingin Anda gunakan

3. Pastikan Anda berada di halaman yang benar Tampilannya seharusnya seperti ini, jika tidak klik pada profiles di sidebar

   

4. Klik pada + tombol

5. Pilih tipe profil Pilih App Store Connect dan klik pada Continue tombol

   

6. Pilih aplikasi yang ingin di-build

   Cari aplikasi Anda di dropdown dan klik Continue tombol

   

7. Pilih distribution certificate yang tepat

   Pilih sertifikat yang Anda ekspor di langkah sebelumnya, lalu klik Continue tombol

   

   Jika Anda tidak yakin sertifikat mana yang harus dipilih, kembali ke Keychain Access dan cari sertifikat yang Anda ekspor. Lalu lihat tanggal kedaluwarsanya.

   

8. Beri nama profil

   Beri nama pada profil tersebut, lalu klik Generate tombol

   Tips

   Nama profil akan diekstrak secara otomatis oleh Capgo CLI — Anda tidak perlu mengingatnya.

   

9. Download profil

   Klik pada Download tombol untuk download profil

   Peringatan

   File ini HARUS DISIMPAN - Anda akan membutuhkannya nanti

   

Selamat 🎉 Sekarang Anda sudah punya semua yang dibutuhkan untuk mengonfigurasi Capgo Native Build.

Peringatan

Jangan pernah commit kredensial yang baru saja Anda buat ke repositori. Jaga keamanannya! 🔒

Menjalankan perintah konfigurasi

Berhasil! Sekarang Anda sudah memiliki semua yang dibutuhkan untuk mengonfigurasi Capgo Native Build.

Perintah yang perlu Anda jalankan adalah:

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

Ganti nilai placeholder

Ganti nilai placeholder di atas dengan kredensial asli yang Anda dapatkan dari langkah sebelumnya:

• --apple-team-id: Apple Team ID Anda
• --apple-key: Jalur ke file yang diunduh .p8 key
• --apple-key-id: Apple Key ID Anda
• --apple-issuer-id: Apple Issuer ID Anda
• --certificate: Jalur ke hasil ekspor Anda .p12 sertifikat
• --ios-provisioning-profile: Jalur ke file yang diunduh .mobileprovision file (bundle ID dideteksi otomatis untuk profil tunggal)

Jika berhasil, Anda akan melihat output berikut:

Auth Apple gagal? Sinkronkan jam Anda

Jika API key di App Store Connect sudah benar tetapi autentikasi tetap gagal, sinkronkan jam komputer Anda dan coba lagi. Capgo menandatangani JWT Apple menggunakan waktu sistem lokal Anda, dan Apple akan menolak token yang kedaluwarsa lebih dari 20 menit ke depan. Selisih waktu beberapa detik saja sudah cukup untuk membuat langkah ini gagal.

Lihat panduan troubleshooting builder untuk langkah sinkronisasi jam.

Setup CI/CD (GitHub Actions)

Jika Anda sudah menyelesaikan ID Tim, Apple key, Apple key ID, dan Apple issuer ID, Sertifikat, dan Profil provisioning, Anda sudah memiliki semua yang dibutuhkan untuk CI/CD. Bagian ini hanya membahas cara memasukkan nilai tersebut sebagai GitHub Actions secrets dan environment variables.

1) Konversi file kredensial ke base64 satu baris

# 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

Tips

Secret GitHub harus berupa nilai satu baris. tr -d '\n' menghapus line break dari output base64.

2) Buat repository secrets

Di GitHub > Repository > Settings > Secrets and variables > Actions, tambahkan:

Nama Secret	Nilai
CAPGO_TOKEN	Token Capgo API Anda
APP_STORE_CONNECT_TEAM_ID	Team ID dari ID Tim
APPLE_KEY_ID	Key ID dari Apple key, Apple key ID, dan Apple issuer ID
APPLE_ISSUER_ID	Issuer ID dari Apple key, Apple key ID, dan Apple issuer ID
BUILD_CERTIFICATE_BASE64	Isi dari certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Dibuat oleh CLI — salin dari .capgo-credentials file
APPLE_KEY_CONTENT	Isi dari apple_key_base64.txt
P12_PASSWORD (opsional)	Anda .p12 kata sandi jika diatur saat ekspor

3) Gunakan env vars di workflow GitHub Actions Anda

.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 }}

Tips

Dengan setup ini, CI hanya mengirim kredensial melalui environment variable. Anda tidak perlu commit file signing atau mengunggahnya sebagai artifact workflow.

Menjalankan build

Sekarang, Anda siap menjalankan build pertama Anda.

Jalankan perintah berikut untuk mem-build aplikasi Anda:

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

Selamat! 🎉 Sekarang, aplikasi Anda sudah berhasil di-build dan siap dikirim ke App Store.

Kirim ke peninjauan App Store

Alur build App Store standar akan mengunggah build ke App Store Connect/TestFlight. Jika rilis CI Anda juga harus melampirkan build TestFlight yang telah diproses ke versi App Store dan mengirimkannya untuk App Review, masukkan --submit-to-store-review dengan build rilis:

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

Ini memerlukan kredensial kunci App Store Connect API (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, dan APP_STORE_CONNECT_TEAM_ID). Upload password khusus aplikasi dan ad_hoc distribusi tidak dapat mengirim build untuk review. --store-release-name adalah versi App Store; jika dikosongkan, Capgo akan membaca MARKETING_VERSION dari proyek Xcode. --store-release-notes adalah teks fallback App Store What’s New, dan setiap --store-release-notes-locale "locale=notes" entri dapat menimpanya untuk lokalisasi store. Gunakan --ios-automatic-release untuk rilis otomatis setelah persetujuan Apple, atau --no-ios-automatic-release untuk menunggu rilis manual. --ios-testflight-groups masih tersedia untuk distribusi beta eksternal, tetapi tidak wajib untuk pengajuan review App Store.

Mode Distribusi Ad-Hoc

Secara default, Capgo melakukan build aplikasi iOS untuk distribusi App Store (TestFlight + App Store). Jika Anda membutuhkan build ad-hoc (untuk pengujian internal atau pengumpulan artefak CI), Anda dapat menggunakan --ios-distribution flag.

Catatan

Distribusi ad-hoc adalah tidak sama dengan distribusi Enterprise (In-House). Distribusi Enterprise memerlukan akun Apple Developer Enterprise terpisah dan menggunakan provisioning profile yang berbeda. Capgo saat ini mendukung app_store dan ad_hoc mode tersebut saja.

Kapan menggunakan mode ad-hoc

• Anda ingin mendistribusikan IPA langsung ke perangkat terdaftar (tanpa TestFlight)
• Anda tidak punya atau tidak ingin memakai key API App Store Connect
• Anda ingin mengumpulkan build artifacts melalui --output-upload tanpa submit ke App Store

Persyaratan

Build ad-hoc memiliki persyaratan yang lebih sedikit dibandingkan build App Store:

Kredensial	Diperlukan?
Sertifikat distribusi (.p12)	Ya
Profil provisioning Ad-hoc (.mobileprovision)	Ya
ID Tim (--apple-team-id)	Ya
Kunci API App Store Connect (.p8)	Tidak
Apple Key ID / Issuer ID	Tidak

Catatan

Di ad_hoc mode, --apple-key, --apple-key-id, dan --apple-issuer-id tidak didukung dan akan diabaikan. Itulah sebabnya dua baris App Store Connect di atas tidak menampilkan flag ad-hoc CLI; opsi ini hanya berlaku untuk app_store mode saja.

Peringatan

Tanpa kunci API App Store Connect, auto-increment build number akan menggunakan fallback berbasis timestamp. Untuk menghilangkan peringatan ini, masukkan --skip-build-number-bump.

Membuat ad-hoc provisioning profile

Ikuti langkah yang sama dengan Profil provisioning, tapi di langkah 5, pilih Ad Hoc alih-alih App Store:

1. Buka Profil Apple Developer
2. Klik + tombol
3. Pilih Ad Hoc dan klik Continue
4. Pilih app dan distribution certificate Anda
5. Pilih perangkat yang ingin didaftarkan
6. Beri nama dan download profilnya

Menyimpan kredensial 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'

Tidak --apple-key, --apple-key-id, atau --apple-issuer-id needed.

Menjalankan ad-hoc build

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

Untuk mengumpulkan IPA sebagai build artifact, tambahkan --output-upload:

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

CI/CD dengan ad-hoc builds

Untuk GitHub Actions, Anda butuh lebih sedikit secrets dibanding build 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

Tips

Perhatikan bahwa APPLE_KEY_ID, APPLE_ISSUER_ID, dan APPLE_KEY_CONTENT tidak diperlukan untuk ad-hoc builds.

Aplikasi dengan Extension (Multi-Target Signing)

Jika aplikasi Anda menyertakan extension (share extensions, widgets, notification service extensions, dll.), setiap target extension memerlukan provisioning profile sendiri. Capgo mendukung ini melalui flag --ios-provisioning-profile flag.

Contoh: 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"

Setiap --ios-provisioning-profile flag memetakan bundle ID ke file provisioning profile-nya. CLI:

1. Membaca setiap file mobileprovision
2. Otomatis mengekstrak nama profil dari plist yang tertanam
3. Meng-encode file ke Base64
4. Menyimpan semuanya sebagai satu CAPGO_IOS_PROVISIONING_MAP kredensial

Tips

Anda butuh satu distribution certificate untuk semua target — hanya provisioning profile yang berbeda per target.

Migrasi dari Single Profile

Jika Anda sebelumnya menggunakan BUILD_PROVISION_PROFILE_BASE64 (single profile), jalankan:

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

Ini mengonversi kredensial single-profile yang ada ke CAPGO_IOS_PROVISIONING_MAP format baru dan menghapus kunci lama (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Setelah migrasi, tambahkan profil ekstensi dengan update perintah (additive merge):

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

Tips

Gunakan update (bukan save) untuk menambahkan profil ke kredensial yang sudah ada. Perintah update ini akan menggabungkan profil baru dengan yang sudah ada. Gunakan save hanya saat mengatur semua kredensial dari awal.

Pemecahan Masalah

Provisioning profile tidak menyertakan capability XYZ.

Terkadang, Anda mungkin melihat error berikut:

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

Ini terjadi karena Anda mengaktifkan capability baru setelah provisioning profile dibuat. Provisioning profile lama belum menyertakan capability baru tersebut.

Untuk memperbaikinya, Anda perlu me-regenerate provisioning profile tersebut.

1. Buka Portal Apple Developer
2. Pilih tim yang sesuai di menu dropdown
3. Klik pada Profiles tombol
4. Cari provisioning profile yang ingin dibuat ulang
5. Klik pada Edit tombol
6. Klik pada Save tombol
7. Klik pada Download tombol
8. Jalankan ulang perintah setup Capgo Native Build dengan profil yang baru diunduh.

Ini seharusnya dapat mengatasi masalah tersebut.

Masalah lainnya

Jika karena alasan apa pun Anda mengalami kendala pada Capgo Native Build, konfigurasi kredensial, atau saat build aplikasi, jangan ragu untuk menghubungi kami melalui dukungan.

Lanjutkan dari iOS Builds

Jika Anda menggunakan Build iOS untuk merencanakan otomatisasi CI/CD, hubungkan dengan CI/CD Capgo untuk workflow produk di Capgo CI/CD, Capgo Native Build untuk workflow produk di Capgo Native Builds, Integrasi Capgo untuk alur kerja produk di Integrasi Capgo, Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan Integrasi GitHub Actions untuk detail implementasi di Integrasi GitHub Actions.