Rilis Tangan Kosong
Menggunakan label rilis di Git dan aplikasi iOS dan Android yang ditandatangani Anda dikirimkan secara otomatis ke TestFlight dan Play Store.
Salin prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.
Mengautomasi pembangunan iOS dan Android secara langsung dari repositori GitHub Anda. Dengan satu file kerja aliran dan beberapa rahasia repositori, setiap push, tag, atau trigger manual dapat menghasilkan aplikasi yang ditandatangani, siap disimpan — tanpa ada anggota tim yang perlu Mac, Xcode, atau Android Studio terinstal.
Rilis Tangan Kosong
Menggunakan label rilis di Git dan aplikasi iOS dan Android yang ditandatangani Anda dikirimkan secara otomatis ke TestFlight dan Play Store.
Tidak Ada Pengaturan Lokal
Kontributor di Windows atau Linux dapat memicu pembangunan iOS. Tidak perlu Xcode, tidak ada masalah sertifikasi, tidak ada sertifikat bersama yang beredar di laptop.
Rahasia Terbatas
Kredensial hidup di GitHub rahasia repository, terbatas pada repo Anda dan hanya dapat dilihat oleh pengguna aliran. Mudah untuk memutar, mudah untuk diverifikasi.
Pembangunan Paralel
Bangun iOS dan Android secara bersamaan dengan menggunakan pekerjaan matrix. Rilis biasanya selesai dalam waktu kurang dari 10 menit.
Sebelum mengatur alur kerja, pastikan Anda telah memiliki:
bunx @capgo/cli@latest app add jika tidak)bunx @capgo/cli@latest build init — lihat Manajemen Kredensial untuk walkthrough sihirbunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI bukan tempat untuk memperbaiki build pertama Andagh) terpasang dan terautentikasi (gh auth login)Pilih Capgo CLI untuk mengexport kredential lokal Anda dalam bentuk file yang siap digunakan. .env Digabungkan dengan gh secret set -f, ini mengubah seluruh pengaturan CI/CD menjadi tiga perintah — tanpa pengkodean base64 manual, tanpa pengaturan JSON, tanpa menyalin-menyunting rahasia secara manual.
Tambahkan kunci Capgo API Anda sebagai rahasia repository
Kunci API tidak termasuk dalam penyimpanan kredential per-aplikasi, jadi tambahkan secara manual:
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"Generate kunci di dashboard __CAPGO_KEEP_0__ Capgo dashboard dengan unggah atau hak akses yang lebih tinggi.
Export kredit Anda ke sebuah .env file
Jalankan manajer kredit interaktif:
bunx @capgo/cli@latest build credentials manage --appId com.example.appIn the TUI, select Ekspor ke .envPengguna CLI menulis .env.capgo.<appId> ke direktori saat ini dengan mode 0600 (hanya dapat dibaca oleh pemilik — misalnya,) .env.capgo.com.example.appKetika kedua iOS dan Android telah dikonfigurasi, rahasia kedua platform akan berada di file yang sama di bawah # === IOS === dan # === ANDROID === Judul bagian. Nama variabel env iOS dan Android berbeda, sehingga menggabungkannya tidak akan menimbulkan konflik.
Pilih file untuk .env file ke GitHub rahasia Actions GitHub
The gh secret set -f perintah membaca file dotenv dan membuat rahasia repositori satu per KEY=value line:
gh secret set -f .env.capgo.com.example.appSemua rahasia yang dibutuhkan oleh alur kerja Anda sudah ada di GitHub. Periksa dengan gh secret list.
Buat file aliran kerja
Tambahkan .github/workflows/capgo-build.yml Tambahkan ke repository Anda. Pilih salah satu pola trigger di bawah ini tergantung pada bagaimana Anda ingin memicu pembangunan.
Untuk Referensi gh secret set -f akan membuat rahasia repository ini (YAML kerja aliran Anda mengacu ke nama-nama ini secara tepat):
| Platform | Rahasia yang dibuat |
|---|---|
| iOS | BUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID |
| Andoid | ANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON |
| (ditambahkan secara manual) | CAPGO_TOKEN |
Anda tidak perlu mengingatnya — contoh aliran kerja di bawah ini sudah mengacu semua dari mereka.
Tiga contoh di bawah ini mencakup pola yang paling umum. Mereka semua menggunakan bentuk yang sama: cek keluar repositori, instal dependensi, bangun aset web, sinkron ke native, kemudian panggil Capgo Bangun dengan kredit yang diberikan sebagai variabel lingkungan.
Mengizinkan siapa pun dengan akses tulis memicu bangun dari Aksi tab di GitHub dengan dropdown platform. Bermanfaat untuk membuat tes ad-hoc atau memulai rilis secara mandiri.
name: Capgo Build (Manual)
on: workflow_dispatch: inputs: platform: description: 'Platform to build' required: true default: 'android' type: choice options: [ios, android, both] mode: description: 'Build mode' required: true default: 'debug' type: choice options: [debug, release]
jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 with: bun-version: latest
- run: bun install --frozen-lockfile - run: bun run build - run: bunx cap sync
- name: Trigger Capgo Build env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }} P12_PASSWORD: ${{ secrets.P12_PASSWORD }} CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }} APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }} APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }} APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }} APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }} ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }} run: | bunx @capgo/cli@latest build request com.example.app \ --platform ${{ inputs.platform }} \ --build-mode ${{ inputs.mode }}Ganti com.example.app dengan ID aplikasi Anda. Setelah disimpan, pergi ke Aksi → Capgo Build (Manual) → Jalankan aliran untuk mengaktifkannya.
Membangun dan mengirimkan kedua platform secara paralel setiap kali Anda mendorong tag versi seperti v1.4.0ini adalah konfigurasi produksi paling umum — git tag v1.4.0 && git push --tags menjadi perintah rilis Anda.
name: Capgo Build (Release)
on: push: tags: - 'v*'
jobs: build: runs-on: ubuntu-latest strategy: fail-fast: false matrix: platform: [ios, android] steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 with: bun-version: latest
- run: bun install --frozen-lockfile - run: bun run build - run: bunx cap sync ${{ matrix.platform }}
- name: Build ${{ matrix.platform }} env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} # iOS BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }} P12_PASSWORD: ${{ secrets.P12_PASSWORD }} CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }} APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }} APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }} APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }} APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }} # Android ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }} run: | bunx @capgo/cli@latest build request com.example.app \ --platform ${{ matrix.platform }} \ --build-mode releaseThe matrix menjalankan iOS dan Android secara paralel pada runner yang terpisah. Pengaturan fail-fast: false berarti bahwa bangunan iOS gagal tidak akan membatalkan bangunan Android yang sedang berlangsung (dan sebaliknya) — berguna ketika salah satu platform memiliki masalah tanda tangan sementara.
Mendetekapi kembali masalah pembangunan asli dengan cepat dengan menghasilkan sebuah debug Android build setiap kali push ke mainMurah untuk dijalankan, feedback cepat, dan Anda bisa melewatkan unggah ke Play Store untuk menjadikannya tes asap yang murni.
name: Capgo Build (Main)
on: push: branches: [main] paths: - 'src/**' - 'android/**' - 'ios/**' - 'package.json' - 'capacitor.config.*'
jobs: smoke-build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 with: bun-version: latest
- run: bun install --frozen-lockfile - run: bun run build - run: bunx cap sync android
- name: Smoke build (Android debug) env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} run: | bunx @capgo/cli@latest build request com.example.app \ --platform android \ --build-mode debug \ --no-playstore-upload \ --output-uploadThe paths filter memastikan alur kerja tidak berjalan pada perubahan dokumen saja. --no-playstore-upload melewatkan unggah ke Play Store (tidak PLAY_CONFIG_JSON diperlukan), dan --output-upload Menghasilkan URL unduh untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat uji.
Untuk build uji, lewati pengiriman toko: Android menggunakan --no-playstore-upload; untuk iOS, bangun dalam mode ad-hoc dengan --ios-distribution ad_hoc (yang tidak pernah mengirimkan ke App Store). Gabungkan salah satu dengan --output-upload untuk mendapatkan URL download sementara untuk file biner.
Dengan default, rilis upload file yang ditandatangani dan meninggalkan aksi toko akhir di bawah kendali Anda. Untuk rilis CI yang harus bergerak langsung ke dalam alur tinjauan toko, tambahkan --submit-to-store-review.
Android menggunakan akun PLAY_CONFIG_JSON service Anda. Tidak ada track eksplisit, --submit-to-store-review menggunakan track produksi dengan release_status: completed. Prefer menyebutkan track di situs panggilan dengan --android-track (atau PLAY_STORE_TRACK), dan override status dengan --android-release-status / PLAY_STORE_RELEASE_STATUS ketika diperlukan:
- name: Submit Android release for review env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }} run: | npx @capgo/cli@latest build request com.example.app \ --platform android \ --build-mode release \ --submit-to-store-review \ --android-track production \ --store-release-name "${GITHUB_REF_NAME}" \ --store-release-notes "Release ${GITHUB_REF_NAME}" \ --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"Untuk rilis internal selesai daripada produksi:
- name: Submit Android internal release env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }} KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }} KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }} KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }} PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }} run: | npx @capgo/cli@latest build request com.example.app \ --platform android \ --build-mode release \ --submit-to-store-review \ --android-track internal \ --store-release-name "${GITHUB_REF_NAME}"iOS menggunakan App Store Connect API path kunci dan mengirimkan build TestFlight yang diproses ke tinjauan App Store. Ini memerlukan app_store distribusi; --ios-testflight-groups adalah opsional untuk distribusi beta eksternal dan tidak diperlukan untuk tinjauan App Store:
- name: Submit iOS build to App Store review env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }} P12_PASSWORD: ${{ secrets.P12_PASSWORD }} CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }} APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }} APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }} APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }} APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }} run: | npx @capgo/cli@latest build request com.example.app \ --platform ios \ --build-mode release \ --ios-distribution app_store \ --submit-to-store-review \ --store-release-name "${GITHUB_REF_NAME}" \ --store-release-notes "Release ${GITHUB_REF_NAME}" \ --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \ --no-ios-automatic-releaseLulus --output-record <path> untuk mempertahankan URL artefak pembangunan dan QR code di disk ketika pembangunan berhasil, kemudian baca kembali di langkah-langkah berikutnya dengan build last-outputTidak ada pencarian log, tidak ada regex.
- name: Build env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} # ...credentials... run: | bunx @capgo/cli@latest build request com.example.app \ --platform android --build-mode debug \ --output-upload --output-retention 1d \ --output-record /tmp/build.json
- name: Comment on PR with build URL env: GH_TOKEN: ${{ github.token }} run: | URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl) if [ -n "$URL" ]; then gh pr comment ${{ github.event.pull_request.number }} \ --body "Debug build ready: $URL" fi--output-record /tmp/build.json menulis sebuah catatan JSON (dengan jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAtdan sebuah QR code PNG di sampingnya di /tmp/build.json.qr.png. build last-output membacanya kembali:
--field outputUrl mencetak hanya URL download (dipisahkan oleh garis baru; aman untuk URL=$(...)).--field qrCodePngPath Mencetak jalur PNG sehingga Anda dapat mengunggahnya sebagai lampiran PR.--qr Mencetak kode QR ASCII yang telah dirender — masukkan ke dalam pagar Markdown code di komentar PR untuk skanabilitas inline.Dengan default, setiap rilis memperbarui nomor pembangunan. Untuk mematikan peningkatan ini, Anda dapat melewatkannya --skip-build-number-bump:
- name: Set version from tag run: | VERSION="${GITHUB_REF#refs/tags/v}" # Update package.json or your version source here bun pm version "$VERSION" --no-git-tag-version
- name: Build env: CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }} # ...credentials... run: | bunx @capgo/cli@latest build request com.example.app \ --platform ios --build-mode release \ --skip-build-number-bumpbun install Sudah cukup cepat sehingga cache dependensi JS jarang memberikan manfaat, tapi dependensi asli Capacitor (CocoaPods, Gradle) layak dicache untuk proyek yang lebih besar.
- uses: actions/cache@v4 with: path: | ~/.bun/install/cache ios/App/Pods android/.gradle key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}| Troubleshooting | Judul bagian ‘Pengaturan’ |
|---|---|
CAPGO_TOKEN is not set | Kunci rahasia tidak ditambahkan, atau pekerjaan tidak memiliki akses ke itu (periksa perlindungan lingkungan/ cabang). |
| Kesalahan Kredensial iOS / Android | gh secret set -f Jangan dijalankan, atau dijalankan terhadap repositori yang berbeda. Periksa dengan gh secret list |
cap sync Kesalahan kredential iOS / Android yang hilang | A plugin asli tidak ada package.json, atau kamu lupa bun install sebelumnya cap sync |
| Aplikasi berhasil dibangun tetapi tidak muncul di App Store Connect | ID tim salah, atau catatan aplikasi belum ada di App Store Connect. Pastikan secara lokal dengan bunx @capgo/cli@latest build credentials manage |
| Proses build terhenti setelah "Mengunggah proyek" | Arsip proyek sangat besar — periksa bahwa node_modules tidak sedang diunggah (hal ini tidak seharusnya secara default) |
Provisioning profile doesn't match bundle ID | Peta provisi mengarah ke ID paket yang berbeda dari yang Xcode sedang menandatangani. Jalankan ulang build init untuk memperbarui profil, kemudian re-export dengan build credentials manage |
| Kredensial berubah secara lokal tetapi CI masih gagal | Tidak lupa untuk re-export dan re-push: bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId> |
| Manajer menolak menulis file kombinasi | Kunci konfigurasi bersama berbeda antara platform — manajer memberi peringatan dan meminta konfirmasi. Konfirmasi untuk menggantikan satu-satunya, atau re-export per-platform dengan --platform ios / --platform android |
build last-output Mencetak URL kosong | Proses build gagal --output-uploadatau gagal sebelum menghasilkan artefak. outputUrl Akan null tercatat. Cabang pada [ -n "$URL" ] sebelum menggunakan |
build last-output kesalahan dengan Unsupported record schemaVersion | Runner berada pada versi CLI yang lebih tua daripada yang menulis catatan. Pin baik produsen dan pembaca pada versi eksplisit yang sama (misalnya bunx @capgo/cli@7.104.0 … pada kedua sisi) daripada @latest, yang mengambang dan dapat berubah-ubah antar pekerjaan |
Untuk gagal bangun platform khusus, lihat panduan Panduan Perbaikan.