Untuk menandatangani dan membangun aplikasi Capacitor di cloud, Anda membuat signing material sekali (keystore Android, sertifikat distribusi iOS, dan provisioning profile), memberikannya ke layanan cloud build, lalu memicu build dari terminal atau CI Anda. Layanan tersebut mengompilasi proyek native, menandatanganinya, dan dapat mengunggahnya langsung ke TestFlight atau Google Play. Panduan ini membahas setiap file signing, cara membuatnya tanpa Mac, cara mengaturnya dengan Capgo Build, dan cara mengotomatiskan build yang ditandatangani dengan aman.
Apa arti “signing in the cloud”
Kedua app store hanya menerima binary yang ditandatangani. Penandatanganan membuktikan bahwa build berasal dari Anda dan tidak ada yang mengubahnya setelahnya. Secara lokal, Xcode dan Android Studio menyembunyikan sebagian besar proses ini. Di cloud, tidak ada yang implisit, jadi Anda perlu tahu persis file mana saja yang terlibat:
| Platform | File | Apa itu | Digunakan untuk |
|---|---|---|---|
| Android | .jks / .keystore |
Keystore yang menyimpan kunci upload Anda | Menandatangani AAB atau APK |
| Android | Akun layanan .json |
Kredensial Google Cloud | Mengunggah ke Google Play |
| iOS | .p12 |
Sertifikat Apple Distribution plus kunci privat | Menandatangani IPA |
| iOS | .mobileprovision |
Provisioning profile yang mengaitkan bundle ID, sertifikat, dan capabilities | Memungkinkan aplikasi untuk dijalankan dan didistribusikan |
| iOS | .p8 + ID kunci + ID penerbit |
API key App Store Connect | Mengunggah ke TestFlight, membaca build numbers |
Jauhkan ini dari Git. Semua di bawah ini menyimpannya di file kredensial lokal Anda atau secret store CI Anda.
Signing Android
Buat keystore upload
Jika aplikasi sudah ada di Google Play, gunakan ulang keystore yang ada. Penandatanganan update dengan key yang berbeda akan ditolak kecuali Anda melalui reset upload key di Play Console.
Untuk aplikasi baru:
keytool -genkeypair -v \
-storetype PKCS12 \
-keystore release.jks \
-alias upload \
-keyalg RSA -keysize 2048 \
-validity 10000
Catatan:
- Google Play mensyaratkan key tersebut berlaku hingga setidaknya 22 Oktober 2033.
-validity 10000(sekitar 27 tahun) mencakup itu. - Dengan tipe store PKCS12, kata sandi key sama dengan kata sandi store.
- Tidak punya JDK? Generator keystore Android menghasilkan file yang sama di browser.
Play App Signing dan upload key
Aplikasi baru di Google Play menggunakan Play App Signing. Google memegang kunci signing aplikasi dan menandatangani ulang apa yang diunduh pengguna. Keystore Anda adalah unggah kunci. Jika hilang, support Play Console bisa mendaftarkan upload key baru, makanya kehilangan kunci ini hanya menunda, bukan bencana. Tetap backup saja.
Service account untuk upload
Untuk upload dari cloud, buat service account di Google Cloud, aktifkan Google Play Android Developer API, download JSON key-nya, lalu undang service account tersebut di Play Console pada menu Pengguna dan izin dengan izin rilis untuk aplikasi Anda. Onboarding Capgo bisa melakukannya lewat Google sign-in, seperti yang ditunjukkan di bawah.
signing iOS
Tiga komponen Apple
- Sertifikat Apple Distribution. Cukup satu per tim, berlaku selama satu tahun. Apple membatasi jumlah yang bisa Anda miliki, jadi jangan buat satu untuk setiap developer.
- Provisioning profile. Menghubungkan bundle ID, sertifikat, dan kapabilitas seperti push notification. Gunakan App Store Connect profil untuk TestFlight dan App Store, serta Ad Hoc profil untuk instalasi pada perangkat terdaftar. Setiap ekstensi aplikasi (widget, share extension, notification service) membutuhkan profilnya sendiri.
- kunci API App Store Connect. Dibuat di bawah Pengguna dan Akses > Integrasi dengan akses App Manager. File
.p8hanya dapat diunduh sekali.
Anda memerlukan hak admin atau account holder di tim Apple Developer untuk membuat ini.
Buat sertifikat tanpa Mac
Alur Keychain Access membutuhkan macOS, tetapi OpenSSL berfungsi di mana saja:
# 1. Private key and certificate signing request
openssl req -new -newkey rsa:2048 -nodes \
-keyout dist.key -out dist.csr \
-subj "/emailAddress=dev@example.com/CN=Example Inc/C=US"
# 2. Upload dist.csr at developer.apple.com > Certificates > + > Apple Distribution
# and download distribution.cer
# 3. Convert and bundle into a .p12
openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -legacy \
-inkey dist.key -in distribution.pem \
-out distribution.p12 -passout pass:choose-a-password
Panduan -legacy flag penting dengan OpenSSL 3: tanpanya, mesin build macOS mungkin gagal mengimpor .p12 dengan “MAC verification failed”. Berbasis browser iOS certificate generator kami melakukan langkah yang sama jika Anda lebih suka tidak menggunakan terminal.
Lalu buat provisioning profile di developer portal (Profil > + > App Store Connect), pilih app ID dan sertifikat baru Anda, lalu download.
Setup signing dengan Capgo Build
Build Capgo mengompilasi dan menandatangani aplikasi Capacitor di mesin yang dikelola Capgo, sehingga Anda bisa build iOS dari Windows atau Linux. Mulai dengan login dan mendaftarkan aplikasi:
bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add
Opsi A: onboarding terpandu (direkomendasikan)
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build init --platform android
Di iOS, onboarding membuat atau menggunakan ulang sertifikat distribusi dan profil provisioning App Store dengan kunci App Store Connect API Anda. Di macOS, proses ini juga bisa memandu Anda membuat kunci API tersebut. Di Android, onboarding membuat atau mengimpor keystore, serta dapat menyiapkan akun layanan Google Cloud dan undangan Play Console melalui sign-in Google. Di akhir, sistem menawarkan untuk memulai build pertama.
Opsi B: simpan file yang sudah ada
Jika Anda sudah memiliki file dari bagian sebelumnya:
# iOS
bunx @capgo/cli@latest build credentials save \
--platform ios \
--certificate ./distribution.p12 \
--p12-password "choose-a-password" \
--ios-provisioning-profile ./AppStore.mobileprovision \
--apple-key ./AuthKey_ABC1234567.p8 \
--apple-key-id ABC1234567 \
--apple-issuer-id 00000000-0000-0000-0000-000000000000 \
--apple-team-id TEAM123456
# Android
bunx @capgo/cli@latest build credentials save \
--platform android \
--keystore ./release.jks \
--keystore-alias upload \
--keystore-key-password "store-password" \
--keystore-store-password "store-password" \
--play-config ./play-service-account.json
Untuk aplikasi dengan ekstensi, ulangi --ios-provisioning-profile dengan bundleId=path mapping untuk setiap target:
--ios-provisioning-profile com.example.app=./App.mobileprovision \
--ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision
Kredensial disimpan di ~/.capgo-credentials/credentials.json, dengan key app ID dan platform. Tambahkan --local untuk menyimpannya di .capgo-credentials.json di proyek sebagai gantinya, lalu tambahkan file itu ke .gitignore. Periksa apa yang tersimpan dengan bunx @capgo/cli@latest build credentials list.
Picu build bertanda tangan
Siapkan proyek native, lalu minta build:
bun run build
bunx cap sync
# iOS: sign with the App Store profile and upload to TestFlight
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
# Android: sign the AAB and upload to the internal track
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release --android-track internal
Logs mengalir ke terminal Anda. Pemindaian pre-build memeriksa masa berlaku sertifikat, kata sandi, dan pairing profil sebelum ada yang di-upload, jadi sebagian besar kesalahan signing gagal dalam hitungan detik, bukan menit. Jalankan sendiri dengan bunx @capgo/cli@latest build prescan --platform ios.
Variasi yang berguna:
| Tujuan | Flags |
|---|---|
| Test build di iPhone terdaftar | --ios-distribution ad_hoc --ios-provisioning-profile ./adhoc.mobileprovision --output-upload |
| APK untuk perangkat MDM atau kiosk | --platform android --no-playstore-upload --output-upload |
| Kirim langsung ke App Review | --submit-to-store-review --store-release-name 2.4.0 |
| Pertahankan nomor build Anda sendiri | --skip-build-number-bump |
| Build bersih tanpa cache | --no-cache |
Untuk build ad hoc, kumpulkan UDID perangkat dulu dengan Pencari UDID iOS lalu tambahkan ke profil tersebut.
Otomatiskan build bertanda tangan di CI
Di CI, gunakan environment variables untuk kredensial alih-alih file kredensial. CLI mengekspor persis apa yang Anda butuhkan:
bunx @capgo/cli@latest build credentials manage --appId com.example.app
# choose "Export to .env"
Di GitHub, push setiap baris ke repository secrets dalam satu perintah, lalu hapus filenya:
gh secret set -f .env.capgo.com.example.app
gh secret set CAPGO_TOKEN --body "your-capgo-api-key"
rm .env.capgo.com.example.app
Workflow rilis yang melakukan signing dan merilis kedua platform saat ada tag:
name: Signed release
on:
push:
tags: ['v*']
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
platform: [ios, android]
steps:
- uses: actions/checkout@v6
- uses: oven-sh/setup-bun@v2
- run: bun install --frozen-lockfile
- run: bun run build
- run: bunx cap sync ${{ matrix.platform }}
- run: bunx @capgo/cli@latest build request com.example.app --platform ${{ matrix.platform }} --build-mode release
env:
CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
Job ini berjalan di Linux. Tanpa macOS runner, tanpa perintah keychain, tanpa fastlane. Environment variables yang sama berlaku di CI mana pun: GitLab CI/CD variables, Bitbucket secured variables, Gitea secrets, atau Azure DevOps variable groups. Panduan per platform: Bitbucket Pipelines, Gitea Actions, dan Dokumentasi GitHub Actions.
Bagaimana key Anda ditangani
Pertanyaan yang wajar sebelum Anda menyerahkan signing key ke layanan cloud mana pun. Dengan Capgo Build:
- Kredensial tersimpan di mesin Anda (
~/.capgo-credentials/) atau di CI secret store Anda. Capgo tidak menyimpan vault key Anda. - Untuk setiap build, CLI mengirimkannya melalui HTTPS. Data tersebut hanya digunakan selama proses build berlangsung dan akan dihapus setelah selesai.
- Hanya native project yang sudah siap yang di-upload. Web source Anda,
.git, dan.envfile-file tersebut tidak. - App yang sudah di-build akan langsung dikirim ke App Store Connect atau Google Play, atau ke link download terbatas jika Anda memintanya.
Konsekuensinya: rotasi kredensial berarti Anda harus memperbarui CI secret sendiri. Ekspor ulang dengan build credentials manage dan push kembali filenya.
Masa berlaku dan rotasi
| Item | Seumur Hidup | Cara mengatasi |
|---|---|---|
| Sertifikat Apple Distribution | 1 tahun | Buat yang baru, regenerasi profil, simpan ulang, perbarui CI |
| Profil provisioning | 1 tahun, atau sampai sertifikatnya dicabut | Regenerasi dan simpan ulang |
| API key App Store Connect | Sampai dicabut | Cabut saat seseorang dengan akses keluar |
| Keystore upload Android | Selama masa berlakunya (atur ke puluhan tahun) | Cadangkan; reset via Play Console jika hilang |
| Kunci service account Play | Sampai dihapus | Rotate tahunan atau saat akses berubah |
Masukkan tanggal Apple ke kalender bersama. Sertifikat kedaluwarsa tidak memengaruhi aplikasi yang sudah ada di perangkat pengguna, tetapi menghalangi setiap build baru.
Pemecahan Masalah
| Error | Penyebab dan solusi |
|---|---|
Provisioning profile doesn't include signing certificate |
Profile dibuat untuk sertifikat yang berbeda. Regenerate dengan yang saat ini. |
Provisioning profile doesn't match bundle ID |
Profile dibuat untuk app ID lain atau tidak memiliki extension target. Tambahkan bundleId=path pemetaan untuk setiap target. |
MAC verification failed |
Salah .p12 password, atau ekspor OpenSSL 3 tanpa -legacy. |
Keystore was tampered with, or password was incorrect |
Password store salah, atau file rusak karena line break base64. |
Key alias not found |
Alias berbeda dari yang ada di keystore. Tampilkan dengan keytool -list -keystore release.jks. |
| Autentikasi App Store Connect gagal | Key ID atau issuer ID salah, key dicabut, atau jam sistem pada mesin penandatangan token tidak sinkron. |
| Play upload: pemanggil tidak memiliki izin | Service account belum diundang di Play Console, atau Android Developer API belum diaktifkan. |
Solusi lainnya ada di Panduan troubleshooting Capgo Build dan CI/CD untuk Capacitor: kesalahan umum.
Setelah signed build pertama
Signed native build hanya diperlukan saat native code berubah. Untuk perubahan JavaScript, CSS, dan HTML, kirimkan live update ke aplikasi yang sudah terinstal sebagai gantinya, dan simpan store build untuk rilis yang mengubah plugin atau konfigurasi native. Jika Anda berasal dari setup berbasis Mac, Build aplikasi iOS dari Windows dengan Capgo Build menunjukkan workflow lengkap tanpa macOS.