Pengaturan Perbaikan

Pembahasan solusi 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 (seharusnya dikecualikan secara otomatis)
   • Cek file-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 kembali perintah build

Trik

Proyek-proyek besar mungkin melebihi batas waktu build (lihat Keterbatasan yang DikenalHubungi dukungan untuk opsi-opsi perusahaan.

Waktu pembangunan melebihi 10 menit

Gejala:

• Pembangunan melebihi waktu yang diizinkan maksimal
• Status menampilkan timeout

Pemecahan masalah:

1. Optimalkan dependensi

   • Hapus paket npm yang tidak digunakan
   • Pilih 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 memerlukan waktu lebih lama
   • Kami dapat menyesuaikan batasan untuk kasus penggunaan tertentu

Issue Autentikasi

”API key tidak valid” atau “Tidak Berwenang”

Gejala:

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

Pembahasan:

1. Periksa kunci API yang 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 kesalahan aplikasi spesifik

Pembahasan:

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
   • API harus memiliki akses ke organisasi aplikasi

Masalah Pembangunan iOS

”Code signing failed”

Gejala:

• Build gagal selama code fase tanda tangan
• Xcode error 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

   # 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

Pengobatan:

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 ulang 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
• API key error

Pembelaan:

1. Periksa kunci API

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

2. Sinkronkan jam komputer Anda

   • Autentikasi App Store Connect menggunakan JWT yang berlaku singkat yang dihasilkan dari waktu sistem lokal Anda
   • Apple menolak token yang akan berakhir lebih dari 20 menit di masa depan, sehingga bahkan sedikit pergeseran jam dapat membuat kunci yang valid lainnya gagal
   • Buka Pengaturan > Waktu & bahasa > Tanggal & waktu dan klik Sinkronisasi sekarang
   • Pada macOS, buka Pengaturan Sistem > Umum > Tanggal & Waktu dan aktifkan waktu otomatis
   • Pada Linux, periksa timedatectl status dan aktifkan NTP jika perlu
   • Setelah sinkronisasi, jalankan kembali Capgo build atau perintah kredential

   Lihat dokumentasi Apple’s Menghasilkan Token untuk API Permintaan aturan masa aktif 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 dicabut

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

   git status ios/App/Podfile.lock

2. Uji instalasi pod secara lokal

   cd ios/App
   pod install

3. Cari pod yang tidak kompatibel

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

Masalah Pembangunan Android

”Kata sandi keystore salah”

Gejala:

• Proses pembangunan gagal selama proses signing
• Error Gradle tentang keystore

Solutions:

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

Solutions:

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

Pembahasan:

1. Test bangun lokal terlebih dahulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Periksa ketergantungan yang hilang

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

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

”Play Store upload failed”

Gejala:

• Pembangunan berhasil tetapi unggah gagal
• Masalah akun layanan

Solusi:

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 terkonfigurasi 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

   • 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

   • Mungkin membutuhkan beberapa detik untuk inisialisasi tugas pembangunan

2. Periksa apakah ID tugas sudah benar

   • Periksa ID tugas dari respons awal pembangunan

3. Periksa apakah pembangunan sudah kadaluarsa

   • Data pembangunan tersedia selama 24 jam

”Gagal sinkronisasi proyek””

Gejala:

• Pembangunan gagal sebelum proses kompilasi dimulai
• Kesalahan file yang hilang

Solutions:

1. Lakukan sinkronisasi Capacitor secara lokal

   bunx cap sync

2. Pastikan semua file native telah dikomit

   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 Uji Coba iOS

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

3. Untuk Toko Play Android

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

Masalah 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. Pastikan 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 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

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

4. Log build (salin output terminal penuh)

5. Informasi lingkungan

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

Hubungi Dukungan

• Discord: Bergabunglah dengan 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 di Mac akan diantrekan untuk memastikan penggunaan optimal
• Ketersediaan download artefak pembangunan bergantung pada tujuan pembangunan dan pengaturan penyimpanan artefak

Keterbatasan-keterbatasan ini mungkin disesuaikan berdasarkan umpan balik.

Prescan menghalangi pembangunanku

Capgo menjalankan lokal pemindaian awal sebelum mengunggah. Perbaiki temuan yang dilaporkan, atau abaikan hanya ID periksa:

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

Lihat katalog lengkap: Pemindaian awal memeriksa.

Sumber Daya Tambahan

• Mulai - Panduan setup awal
• Build iOS - Pengaturan iOS khusus
• Buat Android - Pengaturan Android khusus
• Pengecekan Prescan - Daftar lengkap pengecekan pra-build dan flag ignore
• CLI Referensi - Dokumentasi perintah lengkap