Lompat ke konten

GitHub Aksi

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:

  • A Capgo account with an active subscription and a Capgo API kunci
  • Aplikasi Anda terdaftar di Capgo (bunx @capgo/cli@latest app add jika tidak)
  • Kredensial pembangunan yang dikonfigurasi secara lokal dengan bunx @capgo/cli@latest build init — lihat Manajemen Kredensial untuk walkthrough sihir
  • Sukses build lokal (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI bukan tempat untuk memperbaiki build pertama Anda
  • The GitHub CLI (gh) 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.

  1. Tambahkan kunci Capgo API Anda sebagai rahasia repository

    Kunci API tidak termasuk dalam penyimpanan kredential per-aplikasi, jadi tambahkan secara manual:

    Tutup jendela terminal
    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.

  2. Export kredit Anda ke sebuah .env file

    Jalankan manajer kredit interaktif:

    Jendela terminal
    bunx @capgo/cli@latest build credentials manage --appId com.example.app

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

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

    Jendela Terminal
    gh secret set -f .env.capgo.com.example.app

    Semua rahasia yang dibutuhkan oleh alur kerja Anda sudah ada di GitHub. Periksa dengan gh secret list.

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

Apa yang berakhir di rahasia Anda

Apa yang berakhir di rahasia Anda

Untuk Referensi gh secret set -f akan membuat rahasia repository ini (YAML kerja aliran Anda mengacu ke nama-nama ini secara tepat):

PlatformRahasia yang dibuat
iOSBUILD_CERTIFICATE_BASE64, P12_PASSWORD, CAPGO_IOS_PROVISIONING_MAP_BASE64, APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, APP_STORE_CONNECT_TEAM_ID
AndoidANDROID_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.

.github/aliran kerja/capgo-build-manual.yml
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.

.github/workflows/capgo-build-release.yml
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 release

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

3. Bangunan Debug pada Kirim ke Utama

3. Bangunan Debug pada Kirim Utama

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.

github/workflows/capgo-build-main.yml
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-upload

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

Melewatkan unggah ke Play Store / TesFlight

Judul bagian “Skip Play Store / TestFlight upload”

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

Baca URL keluaran pembangunan dan QR code

Judul bagian “Baca URL keluaran pembangunan dan QR code”

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

bun 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') }}
TroubleshootingJudul bagian ‘Pengaturan’
CAPGO_TOKEN is not setKunci rahasia tidak ditambahkan, atau pekerjaan tidak memiliki akses ke itu (periksa perlindungan lingkungan/ cabang).
Kesalahan Kredensial iOS / Androidgh secret set -f Jangan dijalankan, atau dijalankan terhadap repositori yang berbeda. Periksa dengan gh secret list
cap sync Kesalahan kredential iOS / Android yang hilangA plugin asli tidak ada package.json, atau kamu lupa bun install sebelumnya cap sync
Aplikasi berhasil dibangun tetapi tidak muncul di App Store ConnectID 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 IDPeta 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 gagalTidak 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 kombinasiKunci 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 kosongProses 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 schemaVersionRunner 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.