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
• Error waktu habis setelah 60 detik

Pembahasan:

1. Cek koneksi internet Anda

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

2. Kurangi ukuran proyek

   • Pastikan node_modules/ tidak sedang diunggah (harus dikecualikan secara otomatis)
   • Cari file besar dalam 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

Tip

Proyek besar dapat mengalami batasan waktu build (lihat Keterbatasan yang Dikenal) Hubungi dukungan untuk opsi perusahaan.

”Masa tunggu build setelah 10 menit”

Gejala:

• Waktu build melebihi waktu maksimum yang diizinkan
• Menampilkan status timeout

Solutions:

1. Optimalkan dependensi

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

2. Cek masalah jaringan selama pembangunan

   • Beberapa dependensi mungkin mengunduh file besar selama pembangunan
   • Perhatikan ketergantungan native

3. Jendela terminal

   # 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 key tidak valid” atau “Tidak Berwenang”

Gejala:

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

Pemecahan masalah:

1. Pastikan API key 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

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

Gejala:

• Autentikasi berfungsi 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

Pengobatan:

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 kedaluwarsa
   • Pastikan termasuk ID Aplikasi Anda
   • Konfirmasikan termasuk sertifikat

4. Regenerasi kredit

   • 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 & 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
   • Apple menolak token yang akan berakhir lebih dari 20 menit di masa depan, sehingga bahkan kegesitan jam kecil dapat membuat kunci yang valid gagal
   • Buka Windows, buka Pengaturan > Waktu dan bahasa > Tanggal dan waktu dan klik Sinkronkan sekarang
   • Buka macOS, Pengaturan Sistem > Umum > Tanggal & Waktu dan aktifkan waktu otomatis
   • Pada Linux, periksa timedatectl status dan aktifkan NTP jika diperlukan
   • Sesudah sinkronisasi, jalankan kembali Capgo build atau perintah kredential

   Lihat dokumentasi Apple untuk aturan masa berlaku token App Store Connect. Uji kunci API secara lokal Tutup 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. Periksa kunci API

   • Perluan 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 instalasi Pod”

Gejala:

• Proses pembangunan gagal selama instalasi CocoaPods
• Error di Podfile

Pengembangan:

1. Verifikasi Podfile.lock telah dikomitkan

   git status ios/App/Podfile.lock

2. Test 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 penandatanganan
• 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 encoding base64

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

”Alias kunci tidak ditemukan”

Gejala:

• Tanda tangan gagal dengan kesalahan alias

Solusi:

1. Daftar alias keystore

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

2. Pastikan alias sesuai dengan yang diharapkan

   • Alias sangat sensitif terhadap huruf besar kecil
   • Cek 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

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

3. Verifikasi versi Gradle yang kompatibel

   # 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
• Error 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 Console Play → Setup → API Akses
   • Pastikan akun layanan memiliki akses ke aplikasi Anda
   • Izinkan hak akses ke “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
• Error ID pekerjaan

Solusi:

1. Tunggu sebentar dan coba lagi

   • Pekerjaan bangun mungkin membutuhkan beberapa detik untuk diinisialisasi

2. Periksa apakah ID pekerjaan benar

   • Verifikasi 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
• Kesalahan file yang hilang

Solusi:

1. Jalankan Capacitor secara sinkron lokal

   bunx cap sync

2. Pastikan semua file native telah di-commits

   git status ios/ android/

3. Periksa file-file native yang di-ignore oleh Git

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

”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 unggahan

3. Untuk pengiriman uji coba Android melalui Play Store

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

Issu-Issu Khusus CI/CD

GitHub Aksi: “Komando tidak ditemukan”

Gejala:

• bunx @capgo/cli@latest … Gagal dalam CI dengan “komando tidak ditemukan”

Pemecahan Masalah:

1. Pastikan 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. Pastikan rahasia telah disetel

   • Lihat repo Pengaturan → Rahasia dan variabel → Aksi
   • Tambahkan semua rahasia yang diperlukan

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 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 (seluruh output)

3. ID pekerjaan (dari output pembangunan)

4. Log pembangunan (salin seluruh output terminal)

5. Informasi lingkungan

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

Hubungi Dukungan

• Discord: Join Komunitas Kami
• Email: support@capgo.app
• Documentasi: 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 pada Mac akan diantrekan 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
• Membangun Android - Konfigurasi spesifik Android
• Referensi CLI - Dokumentasi perintah lengkap