Mengatasi Masalah

Solusi untuk masalah umum ketika membuat aplikasi native dengan Capgo Cloud Build.

Kegagalan Bangun

”Gagal Unggah” atau “Koneksi Waktu Out”

Gejala:

• Build gagal selama pengunggahan proyek
• Timeout error setelah 60 detik

Solusi:

1. Periksa koneksi internet Anda

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

2. Kurangi 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 URL upload kadaluarsa

   • URL upload kadaluarsa setelah 1 jam
   • Jika Anda mendapatkan kesalahan URL kadaluarsa, jalankan kembali perintah build

Trik

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

”Waktu build melebihi 10 menit”

Gejala:

• Waktu build melebihi waktu maksimum yang diizinkan
• Status menampilkan timeout

Solutions:

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
   • Pertimbangkan untuk mempercepat dengan menggunakan file lock

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

Issues Autentikasi

”API kunci tidak valid” atau “Tidak Berwenang”

Gejala:

• Proses pembangunan gagal dengan kesalahan autentikasi
• Kode error 401 atau 403

Pembahasan:

1. Periksa apakah kunci API sudah benar

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

2. Periksa izin API

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

3. Pastikan kunci API 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

”App not found” or “No permission for this app”

Gejala:

• Autentikasi berhasil tetapi ada kesalahan aplikasi spesifik

Solusi:

1. Pastikan aplikasi terdaftar

   bunx @capgo/cli@latest app list

2. Periksa apakah ID aplikasi sesuai

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

3. Verifikasi 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:

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

Pembahasan:

1. Pastikan jenis sertifikat sesuai dengan jenis build

   • Build pengembangan memerlukan sertifikat pengembangan
   • Build App Store memerlukan sertifikat distribusi

2. Periksa sertifikat dan profil match

   # 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

   • Periksa tanggal kadaluarsa
   • Pastikan termasuk ID Aplikasi Anda
   • Konfirmasi termasuk sertifikat

4. Regenerasi kredential

   • 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

Solusi:

1. Unduh profil terbaru dari Apple

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

2. Verifikasi 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 profil dengan sertifikat yang benar

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

”Gagal autentikasi App Store Connect”

Gejala:

• Fails upload ke TestFlight
• API key error

Solusi:

1. Verifikasi kunci API

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

2. Sinkronkan jam komputer

   • Autentikasi App Store Connect menggunakan JWT yang berlaku 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 valid lainnya gagal
   • Di Windows, buka Pengaturan > Waktu dan bahasa > Tanggal dan waktu dan klik Sinkronkan sekarang
   • Di macOS, buka Pengaturan Sistem > Umum > Tanggal & Waktu dan aktifkan waktu otomatis
   • Pada Linux, periksa timedatectl status dan aktifkan NTP jika diperlukan
   • Setelah sinkron, jalankan kembali Capgo build atau perintah kredential

   Lihat dokumentasi Apple untuk aturan masa berlaku token App Store Connect. Uji kunci API secara lokal Jendela Terminal

3. Test API key locally

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

4. Check API key permissions

   • Perluan peran “Developer” atau lebih tinggi
   • Verifikasi di App Store Connect -> Pengguna dan Akses -> Kunci

5. Pastikan kunci tidak dibatalkan

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

”Gagal instalasi Pod”

Gejala:

• Proses pembangunan gagal selama instalasi CocoaPods
• Kesalahan Podfile

Pengembangan:

1. Verifikasi Podfile.lock telah dikomitkan

   git status ios/App/Podfile.lock

2. Uji pod install secara lokal

   cd ios/App
   pod install

3. Periksa pod yang tidak kompatibel

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

4. Hapus 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

Pemecahan Masalah:

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

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

”Key alias not found”

Gejala:

• Tanda tangan gagal dengan kesalahan alias

Solusi:

1. Daftar alias keystore

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

2. Verifikasi alias sesuai dengan yang diharapkan

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

3. Gunakan 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 dependensi

Solusi:

1. Test build secara lokal terlebih dahulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Periksa ketergantungan yang hilang

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

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 Unggah Play Store”

Gejala:

• Bangun berhasil tetapi unggah gagal
• Masalah akun layanan

Pembantu:

1. Periksa JSON akun layanan

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

2. Periksa izin akun layanan

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

3. Pastikan aplikasi telah terkonfigurasi di Play Console

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

4. Periksa API telah diaktifkan

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

Masalah Umum

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

Gejala:

• Tidak dapat memeriksa status bangun
• Masalah ID pekerjaan

Solusi:

1. Tunggu sebentar dan coba lagi

   • Pekerjaan bangun mungkin membutuhkan beberapa detik untuk diinisialisasi

2. Periksa apakah ID pekerjaan sudah benar

   • Pastikan ID pekerjaan dari respons bangun awal

3. Periksa apakah bangun sudah kadaluarsa

   • Data bangun tersedia selama 24 jam

”Gagal sinkronisasi proyek”

Gejala:

• Build gagal sebelum proses kompilasi dimulai
• Error file yang hilang

Solutions:

1. Jalankan Capacitor secara sinkron lokal

   bunx cap sync

2. Pastikan semua file native telah dikomit

   git status ios/ android/

3. Cari file native yang diignore oleh Git

   • Ulangi pengaturan .gitignore
   • Pastikan file konfigurasi penting tidak diignore

”Sukses build tapi saya tidak melihat hasil”

Gejala:

• Build menunjukkan kesuksesan tapi tidak ada tautan download

Pengaturan:

1. Periksa pengaturan build

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

2. Untuk pengiriman uji coba iOS melalui TestFlight

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

3. Untuk pengiriman uji coba Android melalui Play Store

   • Periksa Play Console → Pengujian → Pengujian Internal
   • Mungkin membutuhkan beberapa menit untuk diproses

Masalah Khusus CI/CD

GitHub Aksi: “Perintah tidak ditemukan”

Gejala:

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

Solusi:

1. Tetapkan Bun terlebih dahulu jadi bunx tersedia:

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

2. Lalu 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: “Rahasia tidak ditemukan”

Gejala:

• Variabel lingkungan kosong dalam pembangunan

Solusi:

1. Periksa apakah rahasia sudah diset

   • Buka repo Pengaturan → Rahasia dan variabel → Aksi
   • Tambahkan semua rahasia yang dibutuhkan

2. Gunakan sintaks yang benar

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

3. Periksa nama rahasia sesuai

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

Mendapatkan Bantuan Lebih Lanjut

Aktifkan Log Verbal yang Lebih Detail

# 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. Informasi lingkungan

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

Hubungi Dukungan

• Discord: Bergabunglah dengan 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 diurutkan untuk memastikan penggunaan optimal
• Ketersediaan download artefak pembangunan bergantung pada tujuan pembangunan dan konfigurasi penyimpanan artefak

Keterbatasan-keterbatasan ini mungkin disesuaikan berdasarkan umpan balik.

Sumber Daya Tambahan

• Pembelajaran Dasar - Panduan pengaturan awal
• Pembangunan iOS - Konfigurasi spesifik iOS
• Bangun Android - Konfigurasi spesifik Android
• Referensi CLI - Dokumentasi perintah lengkap