Sumber Daya Tambahan

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

Gagal Bangun

Gagal Unggah atau Waktu Koneksi Terlampaui

Gejala:

• Gagal Membangun selama Proses Unggah 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 terunggah (seharusnya dikecualikan secara otomatis)
   • Cek 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 perintah build ulang

Trik

Proyek besar yang sangat mungkin melebihi batas 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

Pemecahan masalah:

1. Optimalkan dependensi

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

2. Periksa masalah jaringan selama pembangunan

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

3. Tinjau ketergantungan 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

Issue Autentikasi

”API key tidak valid” atau “Tidak Berwenang”

Gejala:

• Gagal membangun dengan kesalahan autentikasi
• Kode 401 atau 403

Solusi:

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 berhasil tetapi ada kesalahan aplikasi tertentu

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

Masalah Pembangunan iOS

”Code signing failed”

Gejala:

• Build gagal selama fase code signing
• Xcode mengeluarkan kesalahan 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 apakah 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 sah

   • Periksa tanggal kadaluarsa
   • Periksa apakah termasuk ID Aplikasi Anda
   • Pastikan 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. Rebuat 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:

• Gagal mengunggah ke TestFlight
• API key error

Solusi:

1. Verifikasi kunci API

   • Periksa APPLE_KEY_ID (harus 10 karakter)
   • Periksa APPLE_ISSUER_ID (format UUID)
   • Verifikasi bahwa APPLE_KEY_CONTENT sudah dikodekan base64 dengan benar

2. Sinkronkan jam komputer Anda

   • Autentikasi App Store Connect menggunakan JWT yang berumur pendek 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 untuk Generasi Token untuk API Permintaan aturan masa hidup token App Store Connect.

3. Tes kunci API secara lokal

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

4. Periksa izin kunci API

   • 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
• Error 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 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 penandatanganan
• 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

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

Pembahasan:

1. Test build secara lokal terlebih dahulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Periksa dependensi 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 mengunggah ke Play Store

Gejala:

• Bangun berhasil tetapi unggah gagal
• Error akun layanan

Pembahasan:

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 dapat memeriksa status pembangunan
• Masalah ID Tugas

Solusi:

1. Tunggu sebentar dan coba lagi

   • Pekerjaan pembangunan mungkin membutuhkan beberapa detik untuk diinisialisasi

2. Periksa apakah ID tugas benar

   • Verifikasi ID tugas dari respons awal pembangunan

3. Periksa apakah pembangunan belum kedaluwarsa

   • 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 asli telah di-commit

   git status ios/ android/

3. Periksa file native yang diignore oleh Git

   • Ulangi .gitignore
   • Pastikan file konfigurasi penting tidak diignore

”Sukses build tapi saya tidak melihat hasil”

Gejala:

• Build menunjukkan kesuksesan tapi tidak ada tautan download

Solusi:

1. Periksa konfigurasi build

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

2. Pengajuan iOS TestFlight

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

3. Pengajuan 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 pesan “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 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 ({dari output build})

4. Log Pembangunan (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 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 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

• Mulai - Panduan pengaturan 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