Pengaturan Perbaikan

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

Gagal Bangun

Gagal Mengunggah atau Waktu Koneksi Terlewat

Gejala:

• Gagal Membangun Saat Mengunggah Proyek
• Kesalahan Waktu Setelah 60 Detik

Solutions:

1. Periksa Koneksi Internet Anda

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

2. Perkecil Ukuran Proyek

   • Pastikan node_modules/ tidak diunggah (harus dikecualikan secara otomatis)
   • Cek file besar di proyek Anda:

   find . -type f -size +10M

3. Cek kedaluwarsa URL unggah

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

Trik

Proyek besar mungkin menabrak batasan waktu build (lihat Keterbatasan yang DikenalHubungi dukungan untuk opsi perusahaan.

Waktu pembangunan melebihi 10 menit

Gejala:

• Pembangunan melebihi waktu maksimum yang diizinkan
• Status menampilkan timeout

Pengembangan:

1. Optimalkan dependensi

   • Hapus paket npm yang tidak digunakan
   • Gunakan npm prune --production sebelum melakukan pembangunan

2. Periksa masalah jaringan selama pembangunan

   • Beberapa dependensi mungkin mengunduh file besar selama pembangunan
   • Perhatikan penggunaan file lock sebelum caching

3. Tinjau dependensi native

   # 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:

• Gagal membangun segera dengan kesalahan autentikasi
• Kode 401 atau 403

Solutions:

1. Pastikan kunci API sudah benar

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

2. Periksa izin kunci API

   • Kunci harus memiliki write atau all Periksa di dashboard __CAPGO_KEEP_0__ di bawah __CAPGO_KEEP_1__ Keys
   • Check in Capgo dashboard under API Keys

3. Ensure API key is being read

   # 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

Pengembalian:

1. Pastikan aplikasi terdaftar

   bunx @capgo/cli@latest app list

2. Periksa ID aplikasi sesuai

   • Verifikasi 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 tanda tangan Code””

Gejala:

• Build gagal selama code fase tanda tangan
• Xcode kesalahan tentang sertifikat atau profil

Pengembangan:

1. Pastikan jenis sertifikat sesuai dengan jenis build

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

2. Periksa 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 pengembangan valid

   • Periksa tanggal kadaluarsa
   • Periksa apakah termasuk ID Aplikasi Anda
   • Konfirmasikan 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 tanda tangan tidak termasuk dalam profil pengaturan”

Gejala:

• Xcode tidak dapat menemukan sertifikat di profil

Pembahasan:

1. Unduh profil terbaru dari Apple

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

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

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

”Gagal autentikasi App Store Connect”

Gejala:

• Upload ke TestFlight gagal
• API key error

Pembelaan:

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 sedikit perbedaan waktu juga dapat membuat kunci yang valid gagal
   • Di Windows, buka Pengaturan > Waktu & bahasa > Tanggal & waktu dan klik Sinkronkan sekarang
   • Pada macOS, buka Pengaturan Sistem > Umum > Tanggal & Waktu dan aktifkan waktu otomatis
   • Pada Linux, periksa timedatectl status dan aktifkan NTP jika diperlukan
   • Setelah disinkronkan, jalankan kembali Capgo build atau perintah kredential

   Lihat dokumentasi Apple’s Menghasilkan Token untuk API Permintaan aturan masa hidup token App Store Connect.

3. Tes API kunci secara lokal

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

4. Periksa izin API kunci

   • Kunci memerlukan 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:

• Masalah terjadi selama instalasi CocoaPods
• Gagal Podfile

Pembahasan:

1. Pastikan Podfile.lock telah dikomitkan

   git status ios/App/Podfile.lock

2. Uji instalasi pod secara lokal

   cd ios/App
   pod install

3. Periksa pod yang tidak kompatibel

   • Uji ulang Podfile untuk konflik versi
   • Pastikan semua pod 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

Issues Pembangunan Android

”Kata sandi keystore salah”

Gejala:

• Proses 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:

• Proses tanda tangan gagal dengan kesalahan alias

Solutions:

1. Daftar alias keystore

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

2. Pastikan alias sesuai dengan tepat

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

• Error Gradle umum
• Masalah kompilasi atau dependensi

Pembelaan:

1. Test bangun lokal terlebih dahulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Periksa ketergantungan yang hilang

   • Ulangi build.gradle files
   • Pastikan semua plugin terdaftar dalam dependensi

3. Verifikasi 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 unggah ke Play Store

Gejala:

• Bangun berhasil tetapi unggah gagal
• Error akun layanan

Pengembangan:

1. Verifikasi JSON akun 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 pengujian”

3. Verifikasi aplikasi telah terdaftar 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

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

Issues Umum

”Tidak Ditemukan Tugas” atau “Status Pembangunan Tidak Tersedia”

Gejala:

• Tidak Bisa Memeriksa Status Pembangunan
• Masalah ID Tugas

Pembahasan:

1. Tunggu sebentar dan coba lagi

   • Pembangunan pekerjaan mungkin membutuhkan beberapa detik untuk diinisialisasi

2. Periksa apakah ID pekerjaan sudah benar

   • Periksa ID pekerjaan dari respons pembangunan awal

3. Periksa apakah pembangunan sudah kadaluarsa

   • Data pembangunan tersedia selama 24 jam

”Gagal sinkronisasi proyek”

Gejala:

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

Pembahasan:

1. Lakukan sinkronisasi Capacitor secara lokal

   bunx cap sync

2. Pastikan semua file native telah di-commit

   git status ios/ android/

3. Periksa file native yang diignore oleh Git

   • Ulangi .gitignore
   • Pastikan file konfigurasi penting tidak diignore

”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 iOS TestFlight

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

3. Untuk Android Play Store

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

Issu-Issu Khusus CI/CD

GitHub Aksi: “Komando tidak ditemukan”

Gejala:

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

Solutions:

1. Terlebih dahulu Bun harus diatur 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: “Rahasia tidak ditemukan”

Gejala:

• Variabel lingkungan kosong dalam pembangunan

Solutions:

1. Periksa apakah rahasia sudah diatur

   • 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 rahasia 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

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 Tugas Catatan (dari output build)

4. Log build Salin output terminal penuh

5. Info lingkungan

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

Hubungi Dukungan

• Discord: Join komunitas kami
• Email: support@capgo.app
• Referensi Dokumentasi: Capgo Dokumen

Keterbatasan yang Diketahui

Keterbatasan saat ini:

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

Keterbatasan-keterbatasan ini mungkin disesuaikan berdasarkan umpan balik.

Prescan menghalangi pembangunanku

Capgo menjalankan lokal pemeriksaan awal sebelum unggah. Perbaiki temuan yang dilaporkan, atau abaikan hanya cek id:

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

Lihat katalog lengkap: Pemeriksaan awal memeriksa.

Sumber Daya Tambahan

• Pemula - Panduan pengaturan awal
• Build iOS - Konfigurasi iOS khusus
• Build Android - Konfigurasi Android khusus
• Pemeriksaan Prescan - Daftar lengkap pemeriksaan sebelum build dan flag ignore
• CLI Referensi - Dokumentasi perintah lengkap