GitHub Aksi

Automasi pembangunan iOS dan Android Anda secara langsung dari repositori GitHub Anda. Dengan satu file aliran kerja dan beberapa rahasia repositori, setiap push, tag, atau trigger manual dapat menghasilkan aplikasi yang ditandatangani dan siap disimpan — tanpa ada anggota tim yang perlu memiliki Mac, Xcode, atau Android Studio terinstal.

Apa yang Anda Dapatkan

Rilis Tangan-Bebas

Tagkan rilis di Git dan aplikasi iOS dan Android yang ditandatangani Anda akan disampaikan secara otomatis ke TestFlight dan Play Store.

Tidak Ada Pengaturan Lokal

Kontributor di Windows atau Linux dapat memicu pembangunan iOS. Tidak ada Xcode, tidak ada masalah pengaturan provisi, tidak ada sertifikat tanda tangan bersama yang beredar di laptop.

Rahasia Terbatas

Kredensial hidup di GitHub repository rahasia, terbatas pada repositori Anda dan hanya dapat dilihat oleh pengguna aliran.

Gaya Bangunan Paralel

Bangun iOS dan Android pada saat yang sama dengan menggunakan pekerjaan matrix. Rilis biasanya selesai dalam waktu kurang dari 10 menit.

Persyaratan

Sebelum mengatur aliran kerja, pastikan Anda memiliki:

• Salah satu Capgo dengan langganan aktif dan __CAPGO_KEEP_1__ kunci Capgo API key
• Your app registered in Capgo (bunx @capgo/cli@latest app add lihat —
• __CAPGO_KEEP_0__ bunx @capgo/cli@latest build init __CAPGO_KEEP_1__ Pengelolaan Kredensial untuk panduan walkthrough sihir
• Sukses Membangun Lokal (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI bukanlah tempat untuk memperbaiki bangun pertama Anda
• The GitHub CLI (gh) terpasang dan terotentikasi (gh auth login)

Pertimbangan

Alur di bawah ini mengasumsikan kredensial sudah ada di penyimpanan kredensial lokal Anda (dari build init). Jika Anda belum menyiapkan mereka, lakukan terlebih dahulu — sihir mengelola pembuatan sertifikat, profil penggunaan, keamanan kunci, dan akun layanan Play Store secara interaktif.

Pengaturan

File yang siap digunakan dapat diekspor dari kredential lokal Anda dengan Capgo CLI. .env file. Dengan kombinasi ini, setup CI/CD seluruhnya dapat diubah menjadi tiga perintah — tidak ada pengkodean base64 manual, tidak ada pengaturan JSON, tidak ada salinan-pengganti rahasia secara manual. gh secret set -fTambahkan kunci __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ Anda sebagai rahasia repository.

1. Add your Capgo API key as a repository secret

   The API key isn’t part of the per-app credential store, so add it once manually:

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   upload Capgo dashboard dashboard __CAPGO_KEEP_0__ dashboard __CAPGO_KEEP_0__ atau tingkat yang lebih tinggi.

2. Eksport kredensial Anda ke sebuah .env file

   Jalankan manajer kredensial interaktif:

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

   Dalam TUI, pilih Eksport ke .env. File CLI menulis .env.capgo.<appId> ke direktori Anda saat ini dengan mode 0600 (hanya dapat dibaca oleh pemilik) — misalnya .env.capgo.com.example.app. Ketika kedua iOS dan Android telah dikonfigurasi, rahasia kedua platform berada di dalam file yang sama di bawah # === IOS === dan # === ANDROID === Judul bagian. Nama variabel iOS dan Android terpisah, sehingga menggabungkannya tidak menimbulkan konflik.

   Pentingkah file per-platform?

   Ya --platform ios (atau --platform android) untuk membatasi pengelola ke satu platform. Kemudian, ekspor menghasilkan file per-platform seperti .env.capgo.com.example.app.ios Berguna ketika rahasia iOS dan Android hidup di repositori atau lingkungan yang berbeda.

   Kunci konfigurasi bersama

   Beberapa tombol konfigurasi (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) dapat disimpan di bawah platform masing-masing secara independen dan mungkin telah berbeda. Jika pengelola menemukan perbedaan, maka ia mencetak kunci yang bertentangan, meminta konfirmasi eksplisit sebelum menulis, dan memasukkan daftar konflik sebagai komentar di atas file. Re-ekspor dengan --platform Jika Anda perlu menyimpan nilai per-platform.

3. Push file ke __CAPGO_KEEP_0__ Actions rahasia .env file to GitHub Actions secrets

   perintah membaca file dotenv dan membuat rahasia repository per gh secret set -f baris: KEY=value Jendela terminal

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

   That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.

   File tersebut berisi materi tanda tangan plaintext. Setelah Anda telah memasukkan file ke __CAPGO_KEEP_0__:

   It contains plaintext signing material. Once you’ve pushed it to GitHub:

   echo '.env.capgo.*' >> .gitignore
   rm .env.capgo.*

   Re-export kapan saja Anda perlu memutar kredit — file ini bukanlah artefak yang berumur panjang.

4. Buat file alur kerja

   Tambahkan .github/workflows/capgo-build.yml ke repositori Anda. Pilih salah satu dari tiga pola trigger di bawah ini tergantung pada bagaimana Anda ingin memicu pembangunan.

Apa yang berakhir di rahasia Anda

Sebagai referensi, gh secret set -f akan membuat rahasia repositori ini (YAML alur kerja Anda mengacu ke mereka dengan nama-nama yang 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
Android	ANDROID_KEYSTORE_FILE, KEYSTORE_KEY_ALIAS, KEYSTORE_KEY_PASSWORD, KEYSTORE_STORE_PASSWORD, PLAY_CONFIG_JSON
(ditambah secara manual)	CAPGO_TOKEN

Kamu tidak perlu mengingatnya — contoh alur kerja di bawah sudah mengacu semua dari mereka.

Contoh Alur Kerja

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, lalu panggil Capgo Bangun dengan kredit yang diberikan sebagai variabel lingkungan.

1. Trigger Manual

Mengizinkan siapa pun dengan akses tulis memicu bangun dari Aksi tab di GitHub dengan dropdown platform. Berguna untuk tes ad-hoc atau memulai rilis secara mandiri.

/github/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 di-commit, pergi ke Aksi → Capgo Bangun (Manual) → Jalankan alur kerja untuk mengaktifkannya.

2. Rilis pada Tag

Membangun dan mengirimkan kedua platform secara paralel setiap kali Anda push tag versi seperti v1.4.0Hal ini adalah konfigurasi produksi paling umum — git tag v1.4.0 && git push --tags menjadi perintah rilis Anda.

/github/kerja/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

Matrix menjalankan iOS dan Android secara parallel pada runner yang terpisah. Pengaturan fail-fast: false berarti bahwa build iOS gagal tidak akan membatalkan build Android yang sedang berlangsung (dan sebaliknya) — berguna ketika salah satu platform memiliki masalah tanda tangan sementara.

Catatan

Tentang nomor versi: Capgo Build otomatis meningkatkan nomor build Anda setiap kali melakukan release build. Jika Anda lebih suka memasangkannya ke tag, lihat Lebihkan nomor build di bawah.

3. Debug Build on Push to Main

Menangkap kembali masalah build native awal dengan menghasilkan build debug Android pada setiap push ke utama. main. Murah untuk dijalankan, feedback cepat, dan Anda dapat melewatkan unggah Play Store untuk menjadikannya uji coba 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 aliran kerja tidak berjalan pada perubahan dokumen saja. --no-playstore-upload melewatkan unggah Play Store (tidak PLAY_CONFIG_JSON diperlukan), dan --output-upload menghasilkan URL download untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat uji coba.

Polik Pola

Melewatkan unggah Play Store / Uji Coba TestFlight

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.

Kirimkan rilis toko untuk tinjauan

Dengan default, rilis yang dibangun mengunggah artefak 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 layanan Anda dan mengirimkan rilis Google Play daripada meninggalkannya tidak aktif. Tambahkan PLAY_CONFIG_JSON , dan entri optional --store-release-name, --store-release-notesketika Anda ingin rilis Play membawa tag yang sama dan catatan perubahan lokal sebagai CI: --store-release-notes-locale Salin ke clipboard

- 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 \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${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 penyebaran; --ios-testflight-groups tidak wajib 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

Peringatan

Path ini hanya mengirimkan artefak build. Metadata penjualan toko, kelompok tester, detail kontak tinjauan, jawaban kewajiban, dan pilihan peluncuran masih perlu siap di App Store Connect atau Google Play Console sebelum CI menjalankannya.

Baca URL output build dan QR code

Sukses --output-record <path> untuk mempertahankan URL artefak build dan QR code di disk ketika build berhasil, kemudian baca kembali di langkah-langkah berikutnya dengan build last-outputTidak ada scraping 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 rekaman JSON (dengan jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) dan sebuah PNG QR code di sampingnya pada /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 bisa mengunggahnya sebagai lampiran PR.
• --qr mencetak QR ASCII yang telah dirender — letakkan di dalam pagar Markdown code di komentar PR untuk skannabilitas inline.

Pesan

Rekaman hanya ditulis pada sukses build. Tidak didukung schemaVersion dan tidak diketahui --field nilai keluar dengan kode non-nol, sehingga CLI ketinggalan di runner gagal dengan keras bukan dengan mengemiti URL kosong secara diam-diam.

Melewatkan peningkatan nomor build

Dengan default, setiap rilis build meningkatkan nomor build. Untuk memasangkannya ke nilai yang Anda kendalikan (misalnya, tag Git), pass --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

Menggunakan kembali dependensi

bun install Sudah cukup cepat sehingga cache JS-deps jarang memberikan keuntungan, tetapi 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') }}

Pengaturan

Gejala	Penyebab yang mungkin
CAPGO_TOKEN is not set	Kunci rahasia tidak ditambahkan, atau pekerjaan tidak memiliki akses ke itu (periksa proteksi lingkungan/ cabang)
Kesalahan kredit iOS / Android yang hilang	gh secret set -f tidak dijalankan, atau dijalankan terhadap repositori yang berbeda. Verifikasi dengan gh secret list
cap sync gagal di CI tetapi berfungsi secara lokal	Plugin asli tidak ada di package.json, atau Anda lupa bun install sebelum cap sync
Pembangunan berhasil tetapi tidak ada aplikasi yang muncul di App Store Connect	ID tim salah, atau catatan aplikasi tidak ada di App Store Connect. Verifikasi secara lokal dengan bunx @capgo/cli@latest build credentials manage
Pembangunan berhenti setelah "Mengunggah proyek"	Arsip proyek tidak biasa besar — periksa bahwa node_modules tidak diunggah (tidak seharusnya secara default)
Provisioning profile doesn't match bundle ID	Peta pengaturan menunjuk ke ID paket yang berbeda dari yang Xcode tandatangani. Jalankan ulang build init untuk memperbarui profil, kemudian kembali ekspor dengan build credentials manage
Kredensial berubah secara lokal tetapi CI masih gagal	Jangan lupa untuk kembali ekspor dan kembali push: bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId>
Pengelola menolak menulis file kombinasi	Kunci konfigurasi bersama berbeda antara platform — pengelola memberi peringatan dan meminta konfirmasi. Atau konfirmasi untuk menggantikan satu-satunya, atau kembali ekspor per-platform dengan --platform ios / --platform android
build last-output Mencetak URL kosong	Proses pembangunan tidak berhasil --output-uploadatau gagal sebelum menghasilkan artefak. outputUrl Akan null tercatat di dalam catatan. Cabang pada [ -n "$URL" ] sebelum menggunakan itu
build last-output kesalahan dengan Unsupported record schemaVersion	Pengguna runner berada pada versi CLI yang lebih tua daripada yang menulis catatan. Pastikan baik produsen dan pembaca menggunakan versi yang sama secara eksplisit (misalnya bunx @capgo/cli@7.104.0 … di kedua sisi) daripada @latestyang mengambang dan dapat berubah-ubah antar pekerjaan

Untuk kesalahan pembangunan platform khusus, lihat panduan Panduan Penyelesaian Masalah.

Langkah Selanjutnya

Pengaturan Kredensial Referensi lengkap untuk mempersiapkan kredensial iOS dan Android sebagai rahasia base64.

Pembangunan iOS Panduan yang lebih dalam tentang sertifikat, profil, dan pengiriman ke App Store.

Pembangunan Android Pengaturan Keystore, akun layanan Play Store, dan pengelolaan rasa.

Opsi Konfigurasi Semua CLI flag dan variabel lingkungan untuk mengoptimalkan pembangunan Anda.