Mengatasi Masalah

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

Kegagalan Bangun

”Gagal mengunggah” 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/ bukan sedang diunggah (harus 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

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

Issue Autentikasi

”API kunci tidak valid” atau “Tidak Berwenang”

Gejala:

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

Pemecahan Masalah:

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

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

Masalah Pembangunan iOS

”Gagal Code signing”

Gejala:

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

Solusi:

1. Periksa jenis sertifikat sesuai dengan jenis build

   • Build pengembangan memerlukan sertifikat pengembangan
   • Build 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 provisioning yang valid

   • Periksa tanggal kadaluarsa
   • Periksa apakah termasuk ID aplikasi Anda
   • Konfirmasi apakah 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. Membuat 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
• Error API key

Pembahasan:

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

   • 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 kecil jam 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. Setelah sinkron, jalankan kembali API build atau perintah kredential

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

5. Pastikan kunci tidak dicabut

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

”Gagal instalasi Pod”

Gejala:

• Proses pembangunan gagal selama instalasi CocoaPods
• Error Podfile

Pengembangan:

1. Verifikasi Podfile.lock telah di-commits

   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 signing
• Error Gradle tentang keystore

Pembahasan:

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

”Alias kunci tidak ditemukan”

Gejala:

• Gagal menandatangani dengan kesalahan alias

Solusi:

1. Daftar alias keystore

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

2. Pastikan alias sesuai dengan yang benar

   • 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

   • Ulangi build.gradle files
   • Pastikan semua plugin terdaftar dalam 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 Mengunggah Play Store””

Gejala:

• Bangun berhasil tetapi unggah gagal
• Masalah Akun Layanan

Pengembangan:

1. Pastikan Akun JSON 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
   • 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
• 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

”Project sync failed”

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 native yang di-ignore oleh Git

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

Pembangunan berhasil tetapi saya tidak melihat hasil

Gejala:

• Pembangunan menunjukkan kesuksesan tetapi tidak ada tautan download

Solusi:

1. Periksa konfigurasi pembangunan

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

2. Untuk pengiriman uji coba iOS TestFlight

   • Periksa App Store Connect
   • Proses mungkin memakan waktu 5-30 menit setelah unggahan

3. Untuk Android Play Store

   • Periksa Console Bermain → 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

Pemecahan masalah:

1. Pastikan rahasia telah diset

   • Pergi ke Pengaturan Repo → 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-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: 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

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