Pengaturan Masalah

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

Kegagalan Pembangunan

“Gagal Unggah” atau “Koneksi Masa Tinggal”

Gejala:

• Pembangunan gagal selama unggahan proyek
• Kesalahan waktu tunggu 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)
   • Cek file besar di proyek Anda:

   find . -type f -size +10M

3. Cek kadaluarsa URL unggah

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

Trik

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

“Masa tunggu pembangunan setelah 10 menit”

Gejala:

• Pembangunan melebihi waktu maksimum yang diizinkan
• Status menampilkan timeout

Pemecahan masalah:

1. Optimalkan dependensi

   • Hapus paket npm yang tidak digunakan
   • Pilih npm prune --production sebelum membangun

2. Periksa masalah jaringan dalam pembangunan

   • Beberapa dependensi mungkin mengunduh file besar selama pembangunan
   • Considerasi pra-menyimpan dengan file kunci

3. Ulas 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

Issue Autentikasi

“API kunci tidak valid” atau “Tidak Berwenang”

Gejala:

• Proses pembangunan gagal segera dengan kesalahan autentikasi
• 401 atau 403 kesalahan

Pengembangan:

1. Periksa kunci API apakah 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-autentikasi

   bunx @capgo/cli@latest login

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

Gejala:

• Autentikasi berfungsi tetapi ada kesalahan aplikasi tertentu

Pembahasan:

1. Pastikan aplikasi terdaftar

   bunx @capgo/cli@latest app list

2. Periksa ID aplikasi sesuai

   • Pastikan capacitor.config.json appId
   • Pastikan perintah menggunakan ID aplikasi yang benar

3. Pastikan akses organisasi

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

Issue Pembangunan iOS

Gagal Code signing

Gejala:

• Proses code signing gagal saat membangun
• Xcode mengeluarkan kesalahan tentang sertifikat atau profil

Pembahasan:

1. Pastikan jenis sertifikat sesuai dengan jenis pembangunan

   • Pembangunan perlu sertifikat pengembangan
   • Pembangunan App Store perlu sertifikat distribusi

2. Periksa apakah sertifikat dan profil 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 yang valid

   • Cek tanggal kedaluwarsa
   • Pastikan termasuk ID Aplikasi Anda
   • Pastikan termasuk sertifikat

4. Regenerasi kunci akses

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

“Profil pengaturan tidak termasuk sertifikat tanda tangan”

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 termasuk sertifikat Anda

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. Buat ulang profil dengan sertifikat yang benar

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

“Autentikasi App Store Connect gagal”

Gejala:

• Upload ke TestFlight gagal
• API key kesalahan

Solutions:

1. Verifikasi kunci API

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

2. Sinkronkan jam komputer Anda

   • Autentikasi App Store Connect menggunakan JWT singkat yang dihasilkan dari waktu sistem lokal Anda
   • Apple menolak token yang akan kedaluwarsa lebih dari 20 menit di masa depan, sehingga bahkan perbedaan jam kecil dapat membuat kunci yang sah gagal
   • Buka Pengaturan > Waktu & bahasa > Tanggal & waktu dan klik Sinkronisasi sekarang
   • Buka Pengaturan Sistem > Umum > Tanggal & Waktu dan aktifkan waktu otomatis
   • Periksa timedatectl status dan aktifkan NTP jika diperlukan
   • After syncing, re-run the Capgo build or credential command

   __CAPGO_KEEP_0__ pembangunan atau perintah kredit Menghasilkan Token untuk API Permintaan Dokumentasi untuk aturan masa hidup token App Store Connect.

3. Menguji API kunci secara lokal

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

4. Periksa hak akses API kunci

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

5. Pastikan kunci tidak dicabut

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

“Gagal melakukan ‘Pod install’”

Gejala:

• Pembangunan gagal selama instalasi CocoaPods
• Error Podfile

Pengembangan:

1. Periksa apakah Podfile.lock telah dikomit

   git status ios/App/Podfile.lock

2. Tes instalasi pod secara lokal

   cd ios/App
   pod install

3. Periksa apakah ada pod yang tidak kompatibel

   • Periksa Podfile untuk konflik versi
   • Pastikan semua pods mendukung target pengembangan iOS Anda

4. Membersihkan 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 proses signing
• Error Gradle tentang keystore

Solutions:

1. Periksa kata 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. Periksa pengkodean base64

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

“Alias kunci tidak ditemukan”

Gejala:

• Signing gagal dengan kesalahan alias

Pengembangan:

1. Daftar alias keystore

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

2. Pastikan alias cocok secara tepat

   • Alias sangat sensitif terhadap huruf besar kecil
   • Periksa kesalahan ketik di KEYSTORE_KEY_ALIAS

3. Pakai alias yang benar dari keystore

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

“Gagal Membangun Gradle”

Gejala:

• Masalah Gradle Umum
• Masalah Kompilasi atau Ketergantungan

Pembahasan:

1. Uji bangun lokal terlebih dahulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Cek Ketergantungan yang Hilang

   • Ulangi file build.gradle
   • Pastikan semua plugin terdaftar di dependencies

3. Periksa kompatibilitas versi Gradle

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

4. Membersihkan cache Gradle

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

Gagal mengunggah ke Play Store

Gejala:

• Proses build berhasil tetapi unggahan gagal
• Masalah akun layanan

Solusi:

1. Verifikasi akun JSON layanan

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

2. Periksa izin akun layanan

   • Pergi ke Console Play → Pengaturan → API Akses
   • Pastikan akun layanan memiliki akses ke aplikasi Anda
   • Berikan izin “Rilis ke jalur uji coba”

3. Periksa apakah aplikasi telah disetup di Console Play

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

4. Periksa API telah diaktifkan

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

Issu-Issu Umum

“Tidak Ditemukan” atau “Status Pembangunan Tidak Tersedia”

Gejala:

• Tidak Bisa Memeriksa Status Pembangunan
• Kesalahan ID Tugas

Pembahasan:

1. Tunggu sebentar dan coba lagi

   • Proses pembangunan mungkin membutuhkan beberapa detik untuk diinisialisasi

2. Periksa apakah ID tugas sudah benar

   • Verifikasi ID pekerjaan dari respons pembangunan awal

3. Cek apakah pembangunan belum kedaluwarsa

   • Data pembangunan tersedia selama 24 jam

“Pembangunan proyek gagal”

Gejala:

• Pembangunan gagal sebelum proses kompilasi dimulai
• Kesalahan file hilang

Solutions:

1. Jalankan Capacitor sink lokal

   bunx cap sync

2. Pastikan semua file native telah di-commits

   git status ios/ android/

3. Cari file native yang di-ignore oleh Git

   • Review .gitignore
   • Pastikan file konfigurasi penting tidak di-ignore

“Pembangunan berhasil tetapi saya tidak melihat output”

Gejala:

• Pembangunan menunjukkan kesuksesan tetapi tidak ada tautan download

Solusi:

1. Cek konfigurasi pembangunan

   • Penyimpanan Artifact mungkin tidak terkonfigurasi
   • Hubungi dukungan jika akses artifact tidak tersedia untuk build Anda

2. Untuk pengiriman TestFlight iOS

   • Periksa App Store Connect
   • Proses dapat memakan waktu 5-30 menit setelah unggah

3. Untuk toko Play Android

   • Periksa Play Console → Testing → Internal testing
   • Proses dapat memakan waktu beberapa menit

Build berhasil tetapi artifact salah setelah perubahan lingkungan

Gejala:

• Status build adalah success Tapi IPA/AAB/APK tidak sesuai dengan cabang atau rasa yang Anda bangun terakhir kali
• Android AAB hilang atau salah setelah mengganti kunci RC vs produksi --android-flavor
• Proses build selesai dengan sangat cepat setelah mengubah konfigurasi tanda tangan atau rasa produk

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

Solutions:

1. Pakai kunci cache 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 bersih satu kali ketika debugging:

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

3. Pada API atau integrasi webhook, lewatkan cache_key (misalnya "prod") atau atur cache_enabled: false untuk menjalankan bersih satu kali.

Lihat Pengaturan cache build untuk referensi pilihan lengkap.

Isu Khusus CI/CD

GitHub Aksi: “Perintah tidak ditemukan”

Gejala:

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

Pemecahan Masalah:

1. Pastikan Bun terlebih dahulu sehingga bunx tersedia:

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

2. Kemudian jalankan CLI — bunx mengambilnya secara on demand, tidak perlu instalasi global:

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

GitHub Aksi: “Tidak Ditemukan Rahasia”

Gejala:

• Variabel lingkungan kosong dalam pembangunan

Pembatasan:

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 nama rahasia sesuai

   • Nama sangat sensitif terhadap huruf besar kecil
   • Tidak ada kesalahan tata bahasa dalam referensi rahasia

Mendapatkan Bantuan Lebih Lanjut

Aktifkan Pemantauan Verbal

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

Kumpulkan Informasi Pembangunan

Ketika 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 pekerjaan (dari output pembangunan)

4. Log pembangunan (salin output terminal lengkap)

5. Info lingkungan

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

Hubungi Dukungan

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

Keterbatasan yang Dikenal

Keterbatasan saat ini:

• Waktu pembangunan maksimum: 10 menit
• Ukuran unggahan maksimum: ~500MB
• Pembangunan iOS memerlukan sewa Mac selama 24 jam, pembangunan di Mac akan menunggu 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 terblokir oleh prescan

Capgo menjalankan prescan lokal prescan sebelum mengunggah. Perbaiki temuan yang dilaporkan, atau abaikan hanya ID periksaan tersebut:

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

Melihat katalog lengkap: Pengecekan awal:.

Sumber Daya Tambahan

• Mulai - Panduan pengaturan awal
• Pilihan Konfigurasi - CLI flag-termasuk --cache-key dan --no-cache
• Build iOS - Pengaturan khusus iOS
• Build Android - Konfigurasi spesifik Android
• - Pengecekan awal - Daftar lengkap pengecekan sebelum membangun dan flag ignore
• CLI Referensi - Dokumentasi perintah lengkap