Build Aplikasi iOS dari Linux dengan Capacitor dan Capgo Build

Linux adalah tempat yang nyaman untuk menulis aplikasi Capacitor, dan Android pun bisa di-build tanpa kendala. iOS adalah pengecualian: Xcode dan tool signing Apple hanya berjalan di macOS. Solusinya bukan menaruh Mac mini di bawah meja, melainkan men-generate project iOS secara lokal dan mengompilasinya di macOS via cloud.

Panduan ini adalah versi Linux dari Build aplikasi iOS dari Windows dengan Capacitor dan Capgo Build. Panduan ini membahas bagian yang berbeda di Linux: sertifikat OpenSSL, Linux shell, dan CI dari Linux runners.

Pembagian tugas

Aplikasi Capacitor memiliki dua build:

• Build web: output framework Anda di dalam dist/. Dilakukan di Linux.
• Native Build: Xcode archive, signing, upload. Dilakukan oleh Capgo Build pada mesin Apple Silicon yang menjalankan macOS dan Xcode terbaru.

CLI mengunggah file yang telah disiapkan ios/ proyek dari mesin Anda. Tidak perlu ada di Git host, dan tidak ada kredensial registry privat yang keluar dari perangkat Anda, karena instalasi dependency dan cap sync terjadi secara lokal sebelum upload.

Prerequisites

• Aplikasi Capacitor yang bisa di-build secara lokal (framework apa pun).
• Node 20+ atau Bun di Linux.
• Keanggotaan Apple Developer Program.
• OpenSSL (sudah terinstal secara default di hampir semua distro).
• Akun Capgo dan aplikasi yang sudah terdaftar di bunx @capgo/cli@latest app add.

1) Generate proyek iOS di Linux

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios

Anda akan melihat sesuatu seperti Skipping pod install because CocoaPods is not installed. Ini wajar. Folder ios/ tersebut ada dan harus di-commit; folder ini berisi bundle ID, Info.plist, ikon, dan pengaturan native Anda.

2) Sync aset web sebelum setiap build

bun run build
bunx cap sync ios

cap sync menyalin dist/ ke dalam ios/App/App/public dan memperbarui referensi plugin. Capgo mengompilasi apa yang ada di ios/, jadi proyek yang belum disinkronkan akan mengirimkan UI sebelumnya.

3) Buat signing material tanpa Mac

Anda butuh tiga hal: sertifikat Apple Distribution sebagai .p12, profil provisioning App Store, dan kunci API App Store Connect. Tidak ada yang butuh Keychain Access.

Sertifikat Distribution dengan OpenSSL

openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Your Name/C=US"

Upload ios_distribution.csr di Certificates, Identifiers & Profiles, pilih Apple Distribution, lalu download distribution.cer. Konversi dan bundle:

openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

Panduan -legacy flag sangat penting dengan OpenSSL 3. Tanpa itu, tooling Apple akan menolak .p12 dengan error password tidak valid padahal password sudah benar. Jika Anda tidak ingin berurusan dengan OpenSSL, generator sertifikat iOS melakukan hal yang sama di browser.

Provisioning profile dan kunci API

Di portal Apple Developer, buat profil App Store untuk bundle ID Anda menggunakan sertifikat baru dan unduh .mobileprovision. Di App Store Connect, buat kunci API dengan role App Manager dan unduh .p8; catat Key ID dan Issuer ID. panduan build iOS menampilkan setiap layar.

Ingin memeriksa profil di Linux? openssl smime -inform der -verify -noverify -in profile.mobileprovision mencetak plist yang tertanam.

4) Simpan kredensial di Capgo

bunx @capgo/cli@latest login
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id "TEAMID" \
  --apple-key ./AuthKey_KEYID.p8 \
  --apple-key-id "KEYID" \
  --apple-issuer-id "issuer-uuid" \
  --certificate ./ios_distribution.p12 \
  --ios-provisioning-profile ./App_Store.mobileprovision

Atau jalankan bunx @capgo/cli@latest build init --platform ios untuk versi panduan. Di Linux, langkah kunci App Store Connect dilakukan manual; sisanya akan dipandu lewat prompt.

Jika Apple menolak key dengan error autentikasi, sinkronkan jam Anda. JWT ditandatangani dengan waktu lokal dan Apple menolak token yang selisih waktunya terlalu jauh:

timedatectl status
sudo timedatectl set-ntp true

5) Request build

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

Yang telah disiapkan ios/ project di-upload, Capgo menjalankan pod install, melakukan archive dengan Xcode, signing dengan sertifikat Anda, dan streaming logs ke terminal. Dengan key API yang sudah dikonfigurasi, build akan otomatis dikirim ke TestFlight setelah selesai. Install aplikasi TestFlight di iPhone untuk menjalankannya.

Build yang gagal dapat didiagnosis secara otomatis dengan menambahkan --ai-analytics; Diagnosis build AI membaca log Xcode dan menjelaskan cara memperbaikinya.

6) Ad hoc builds untuk tester tanpa TestFlight

Untuk perangkat QA yang terdaftar via UDID, gunakan profil Ad Hoc dan simpan IPA sebagai artefak:

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

CLI akan mencetak link download berbatas waktu. Tambahkan --output-record build.json untuk menyimpan link dan QR code bagi tester.

7) Automasi dari Linux CI runner

Perintah yang sama bisa dijalankan di Linux CI mana pun. Contoh GitHub Actions:

name: iOS build
on:
  workflow_dispatch:
jobs:
  ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run build
      - run: bunx cap sync ios
      - run: bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Credentials yang disimpan di langkah 4 tersimpan di Capgo, jadi runner hanya butuh token. Atau, ekspor CI .env dengan bunx @capgo/cli@latest build credentials manage dan masukkan nilainya sebagai secrets; lihat cara mengelola credentials.

8) Iterasi harian tanpa native builds

Setelah build TestFlight tersedia, sebagian besar perubahan adalah perubahan web. Push perubahan tersebut dengan Capgo Live Updates:

bun run build
bunx @capgo/cli@latest bundle upload --channel production

Cadangkan build request untuk penambahan plugin, perubahan izin, perubahan ikon, dan upgrade Capacitor.

Kendala di Linux

• Lupa cap sync ios: IPA menampilkan UI lama. Lakukan sync sebelum setiap request.
• ios/ di .gitignore: CLI di-upload dari disk sehingga tetap build, tapi rekan tim dan CI tidak akan punya native project. Segera commit.
• .p12 password ditolak: buat ulang dengan -legacy.
• Autentikasi Apple gagal: clock drift. Aktifkan NTP.
• Plugin ditambahkan, lupa native rebuild: menambahkan plugin Capacitor akan mengubah binary native. Jalankan cloud build baru dan submit ke store sebelum merilis perubahan web yang memanggilnya.

Ringkasan

Linux tidak bisa menjalankan Xcode, tapi juga tidak perlu. Buat ios/ dengan Capacitor, buat sertifikat build pakai OpenSSL, dan biarkan Capgo Build yang compile, sign, dan kirim ke TestFlight. Dengan Live Updates untuk web layer, tim yang hanya pakai Linux bisa merilis iOS sama rutinnya dengan Android. Untuk setup environment lengkap, baca Development Capacitor di Linux.