Penyelesaian Masalah

Solutions untuk masalah umum ketika membangun aplikasi native dengan Capgo Cloud Build.

Gagal Bangun

“Gagal mengunggah” atau “Koneksi waktu out”

Gejala:

• Gagal membangun aplikasi selama unggahan proyek
• Error waktu keluar setelah 60 detik

Solutions:

1. Periksa koneksi internet Anda

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. Mengurangi ukuran proyek

   • Pastikan node_modules/ tidak sedang diunggah (seharusnya dikecualikan secara otomatis)
   • Periksa file besar di proyek Anda:

   find . -type f -size +10M

3. Periksa kedaluwarsa URL unggah

   • URL unggah akan kedaluwarsa setelah 1 jam
   • Jika Anda mendapatkan kesalahan URL kedaluwarsa, jalankan perintah build ulang

Tip

Proyek yang sangat besar mungkin mencapai batas waktu pembangunan (lihat Keterbatasan yang Dikenal) Hubungi dukungan untuk opsi perusahaan.

“Waktu pembangunan setelah 10 menit”

Gejala:

• Pembangunan melebihi waktu maksimum yang diizinkan
• Status menampilkan timeout

Pembahasan:

1. Optimalkan dependensi

   • Hapus paket npm yang tidak digunakan
   • Gunakan npm prune --production Sebelum membangun

2. Periksa masalah jaringan selama pembangunan

   • Beberapa dependensi mungkin mengunduh file besar selama pembangunan
   • Consider pre-caching dengan file lock

3. Tinjau dependensi asli

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. Hubungi dukungan

   • Jika aplikasi Anda memang memerlukan waktu lebih lama
   • Kami dapat menyesuaikan batasan untuk kasus penggunaan tertentu

Issues Autentikasi

“Kunci API tidak valid” atau “Tidak Berwenang”

Gejala:

• Proses pembangunan gagal secara langsung dengan kesalahan autentikasi
• Kode 401 atau 403

Pembahasan:

1. Periksa kunci API apakah sudah benar

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. Periksa izin kunci API

   • Kunci harus memiliki write atau all Izin
   • Periksa di Capgo dashboard di bawah API Keys

3. Pastikan API kunci sedang dibaca

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. Re-authenticate

   bunx @capgo/cli@latest login

“Aplikasi tidak ditemukan” atau “Tidak ada izin untuk aplikasi ini”

Gejala:

• Autentikasi berfungsi tetapi ada kesalahan aplikasi spesifik

Solutions:

1. Pastikan aplikasi terdaftar

   bunx @capgo/cli@latest app list

2. Periksa ID aplikasi sesuai

   • Pastikan capacitor.config.json appId
   • Ensure command uses correct app ID

3. Pastikan akses organisasi

   • Periksa apakah Anda berada di organisasi yang benar
   • API harus memiliki akses ke organisasi aplikasi

Masalah Pembangunan iOS

"Code gagal menandatangani"

Gejala:

• Pembangunan gagal selama fase code menandatangani
• Error Xcode tentang sertifikat atau profil

Solutions:

1. Periksa jenis sertifikat sesuai dengan jenis pembangunan

   • Pembangunan pengembangan memerlukan sertifikat pengembangan
   • Pembangunan App Store memerlukan sertifikat distribusi

2. Periksa sertifikat dan profil yang sesuai

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. Pastikan profil pengaturan valid

   • Periksa tanggal kadaluarsa
   • Verifikasi apakah termasuk ID Aplikasi Anda
   • Konfirmasi apakah termasuk sertifikat

4. Regenerasi kunci akses

   • Hapus sertifikat/ profil lama
   • Buat yang baru di portal Pengembang Apple
   • Re-encode dan update variabel lingkungan

“Sertifikat penandatangan tidak ada di profil pengaturan”

Gejala:

• Xcode tidak dapat menemukan sertifikat di profil

Solutions:

1. Unduh profil terbaru dari Apple

   • Pergi ke Portal Pengembang Apple → Sertifikat, ID, dan Profil
   • Unduh profil pengembangan
   • Pastikan sertifikat Anda termasuk

2. Periksa apakah sertifikat ada di profil

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. Rebuat profil dengan sertifikat yang benar

   • Pada portal pengembang Apple, edit profil
   • Pastikan sertifikat distribusi Anda dipilih
   • Unduh dan re-encode

“Gagal autentikasi App Store Connect”

Gejala:

• Upload ke TestFlight gagal
• Kunci API kesalahan

Pembahasan:

1. Verifikasi kunci API

   • Periksa APPLE_KEY_ID (harus 10 karakter)
   • Periksa APPLE_ISSUER_ID (dalam format UUID)
   • Verifikasi APPLE_KEY_CONTENT telah dikodekan base64 dengan benar

2. Sinkronkan jam komputer Anda

   • Autentikasi App Store Connect menggunakan token JWT yang berumur pendek yang dihasilkan dari waktu sistem lokal Anda
   • Apple menolak token yang akan kedaluwarsa lebih dari 20 menit di masa depan, sehingga bahkan perbedaan waktu kecil dapat membuat kunci yang valid lainnya gagal
   • Buka Windows, buka Pengaturan > Waktu dan bahasa > Tanggal dan waktu dan klik Sinkron sekarang
   • Buka macOS, buka Pengaturan Sistem > Umum > Tanggal dan Waktu dan aktifkan waktu otomatis
   • Pada Linux, periksa timedatectl status dan aktifkan NTP jika perlu
   • Setelah sinkronisasi, jalankan kembali Capgo build atau perintah kredential

   Lihat Apple's Generasi Token untuk Permintaan API Dokumentasi Apple untuk aturan masa aktif token App Store Connect.

3. Uji kunci API secara lokal

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. Lihat kunci API izin

   • Kunci memerlukan peran 'Developer' atau lebih tinggi
   • Periksa di App Store Connect -> Pengguna dan Akses -> Kunci

5. Pastikan kunci tidak dicabut

   • Periksa di App Store Connect
   • Buat kunci baru jika diperlukan

App mengalami crash saat peluncuran di iOS 27

Gejala:

• Applikasi yang dibangun dengan Xcode 27 langsung menutup pada iOS 27 (TestFlight atau perangkat)
• Laporan crash menampilkan _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Pembahasan: Applikasi yang dibangun dengan iOS 27 SDK harus menerapkan siklus kehidupan UIScene. Tambahkan SceneDelegate dan UIApplicationSceneManifest ke ios/App/App/Info.plistatau bangun dengan --xcode-version 26.Capgo sekarang menghalangi pembangunan ini sebelum mereka dimulai (pemeriksaan awal) ios/plist-scene-lifecycle-xcode27).

“Gagal Install Pod”

Peringatan

Capgo Pembangunan berhenti membangun proyek CocoaPods pada Desember 2026. Migrasi ke Manager Paket Swift: lihat panduan Capacitor Panduan SPM.

Gejala:

• Proses pembangunan gagal selama instalasi CocoaPods
• Error Podfile

Pembahasan:

1. Pastikan Podfile.lock telah dikomit

   git status ios/App/Podfile.lock

2. Tes instalasi pod secara lokal

   cd ios/App
   pod install

3. Periksa pod yang tidak kompatibel

   • Ulangi Podfile untuk konflik versi
   • Pastikan semua pod mendukung target pengembangan iOS Anda

4. Bersihkan cache pod

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Masalah Pembangunan Android

“Kata sandi keystore salah”

Gejala:

• Pembangunan gagal selama tanda tangan
• Kesalahan Gradle tentang keystore

Solusi:

1. Verifikasi kunci sandi keystore

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. Periksa variabel lingkungan

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Verifikasi pengkodean base64

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

“Alias kunci tidak ditemukan”

Gejala:

• Gagal menandatangani dengan kesalahan alias

Pembahasan:

1. Daftar alias keystore

   keytool -list -keystore my-release-key.keystore

2. Periksa apakah alias cocok secara tepat

   • Nama alias sensitif terhadap huruf besar kecil
   • Periksa ejaan di KEYSTORE_KEY_ALIAS

3. Pakai alias yang benar dari keystore

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

“Pembangunan Gradle gagal”

Gejala:

• Masalah Gradle umum
• Masalah kompilasi atau dependensi

Solusi:

1. Uji bangun lokal terlebih dahulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Periksa ketergantungan yang hilang

   • Tinjau file build.gradle
   • Pastikan semua plugin terdaftar di ketergantungan

3. Verifikasi kompatibilitas versi Gradle

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Hapus cache Gradle

   cd android
   ./gradlew clean
   rm -rf .gradle build

“Gagal mengunggah ke Play Store”

Gejala:

• Build berhasil tetapi upload gagal
• Masalah akun layanan

Pembahasan:

1. Pastikan akun JSON layanan

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. Periksa Izin Akun Layanan

   • Go to Play Console → Setup → API Access
   • Pergi ke Console Play → Setup → __CAPGO_KEEP_0__ Akses
   • Pastikan akun layanan memiliki akses ke aplikasi Anda

3. Berikan izin “Rilis ke jalur uji coba”

   • Aplikasi harus dibuat terlebih dahulu di Play Console
   • Setidaknya satu APK harus diunggah secara manual secara awal

4. Periksa API telah diaktifkan

   • Pengembang Google Play API harus diaktifkan
   • Periksa di Google Cloud Console

Issues Umum

“Tidak ditemukan pekerjaan” atau “Status bangun tidak tersedia”

Gejala:

• Tidak dapat memeriksa status bangun
• Error ID pekerjaan

Solutions:

1. Tunggu sebentar dan coba lagi

   • Proses build mungkin membutuhkan beberapa detik untuk diinisialisasi

2. Periksa apakah ID pekerjaan sudah benar

   • Verifikasi ID pekerjaan dari respons build awal

3. Periksa apakah build sudah kadaluarsa

   • Data build tersedia selama 24 jam

“Gagal sinkronisasi proyek”

Gejala:

• Build gagal sebelum proses kompilasi dimulai
• Error file tidak ditemukan

Solutions:

1. Jalankan Capacitor secara lokal secara sinkron

   bunx cap sync

2. Pastikan semua file asli telah di-commits

   git status ios/ android/

3. Pastikan semua file asli native telah di-commits

   • Periksa .gitignore
   • Pastikan file konfigurasi penting tidak diabaikan

Pastikan file konfigurasi penting tidak di-ignores

Gejala:

• Tampilan Build Berhasil, Tapi Tidak Ada Link Download

Pengembangan:

1. Periksa konfigurasi build

   • Penyimpanan artefak mungkin tidak dikonfigurasi
   • Hubungi dukungan jika akses artefak tidak tersedia untuk build Anda

2. Untuk Pengiriman Aplikasi ke TestFlight iOS

   • Untuk pengiriman iOS TestFlight
   • Pengolahan mungkin membutuhkan waktu 5-30 menit setelah unggahan.

3. Untuk Toko Aplikasi Android

   • Periksa Console Mainan → Pengujian → Pengujian Internal
   • Pengolahan mungkin membutuhkan beberapa menit.

Sukses build tetapi artefak salah setelah perubahan lingkungan

Gejala:

• Status build adalah success tetapi IPA/AAB/APK tidak sesuai dengan cabang atau rasa yang baru saja dibangun
• Android AAB hilang atau salah setelah mengganti RC vs kredit produksi atau --android-flavor
• Build selesai dengan cepat setelah mengubah konfigurasi tanda tangan atau rasa produk

Penyebab: Capgo memulihkan cache build per aplikasi oleh default (hilangkan cache_key untuk cache umum bersama). Jika RC dan produksi menggunakan ID aplikasi yang sama tanpa kunci yang terpisah, pemulihan dapat menggunakan hasil kompilasi dari lingkungan sebelumnya.

Solutions:

1. Pilih Cache Key per Lingkungan (direkomendasikan untuk pipa RC/PROD yang berlangsung):

   # Production
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=prod \
     --android-flavor production
   
   # Staging / RC
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=staging \
     --android-flavor staging

2. Bangun ulang dengan membangun yang bersih Kerjakan Bangunan Bersih Satu Kali

   bunx @capgo/cli@latest build request com.example.app --platform android --no-cache

3. Dalam API atau integrasi webhook, pass cache_key , lewatkan (misalnya "prod") atau set cache_enabled: false untuk menjalankan satu kali saja.

Lihat Cache Pembangunan untuk referensi pilihan lengkap.

Masalah Khusus CI/CD

GitHub Aksi: “Perintah tidak ditemukan”

Gejala:

• bunx @capgo/cli@latest … gagal di CI dengan “perintah tidak ditemukan”

Solusi:

1. Konfigurasi Bun terlebih dahulu sehingga bunx Dapat diakses:

   - uses: oven-sh/setup-bun@v2

2. Lalu jalankan CLI — bunx mengunduhnya secara dinamis, tidak perlu instalasi global.

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub Actions: “Secrets not found”

Symptoms:

• Variabel lingkungan kosong dalam pembangunan

Solutions:

1. Periksa apakah rahasia telah disetel

   • Pergi ke Pengaturan Repo → Rahasia dan Variabel → Aksi
   • Tambahkan semua rahasia yang diperlukan

2. Pakai sintaks yang benar

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. Periksa apakah nama rahasia sesuai

   • Nama nama sangat sensitif terhadap huruf besar kecil
   • Tidak ada kesalahan ketik dalam referensi rahasia

Mendapatkan Bantuan Lebih Lanjut

Aktifkan Log Verifikasi

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

Kumpulkan Informasi Pembangunan

Jika menghubungi dukungan, termasuk:

1. Perintah pembangunan yang digunakan

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. Pesan kesalahan (output lengkap)

3. ID Tugas (dari output pembangunan)

4. Build logs (salin keluaran terminal penuh)

5. Info Lingkungan

   node --version
   npm --version
   bunx @capgo/cli@latest --version

Kontak Dukungan

• Discord: Join Komunitas Kami
• Email: Bantuan@capgo.app
• Dokumentasi: Dokumen Capgo

Keterbatasan yang Dikenal

Keterbatasan saat ini:

• Waktu pembangunan maksimum: 10 menit
• Ukuran unggah maksimum: ~500MB
• Pembangunan iOS memerlukan sewa Mac selama 24 jam, pembangunan di Mac akan diantrekan untuk memastikan penggunaan optimal
• Ketersediaan download artefak pembangunan bergantung pada tujuan pembangunan dan pengaturan penyimpanan artefak

Keterbatasan-keterbatasan ini mungkin disesuaikan berdasarkan umpan balik.

Pembangunan Prescan diblokir

Capgo menjalankan pembangunan lokal Preskans Sebelum mengunggah. Perbaiki temuan yang dilaporkan, atau abaikan hanya ID pengecekan:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

Temukan katalog lengkap: Pengecekan Preskans.

Sumber Daya Tambahan

• Mulai Menggunakan - Panduan pengaturan awal
• Pilihan Konfigurasi - Flag CLI termasuk --cache-key dan --no-cache
• Build iOS - Konfigurasi iOS khusus
• Build Android - Konfigurasi Android khusus
• Pemeriksaan awal - Daftar lengkap pemeriksaan sebelum membangun dan flag ignore
• Referensi CLI - Dokumentasi perintah lengkap