Langsung ke konten utama

Cara Sign dan Build Aplikasi Capacitor di Cloud

Sign dan build app Capacitor Anda di cloud: buat Android keystore dan iOS certificate, simpan kredensial dengan aman, dan jalankan signed build dari CI.

Sertifikat iOS dan keystore Android yang dipakai untuk menandatangani aplikasi Capacitor di cloud build

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 .p8 hanya 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
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 .env file-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.

Live updates untuk aplikasi Capacitor

Saat bug web-layer sudah live, kirim perbaikannya lewat Capgo alih-alih menunggu berhari-hari untuk persetujuan app store. Pengguna mendapat update di background, sementara perubahan native tetap mengikuti jalur review normal.

Terbaru dari Blog kami

Capgo memberikan insight terbaik yang Anda butuhkan untuk membuat aplikasi mobile yang benar-benar profesional.