GitHub Aksi

Automasi pembangunan iOS dan Android Anda secara langsung dari repositori GitHub Anda. Dengan satu file alur 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

Pelepasan Tangan

Tagkan pelepasan di Git dan biner 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 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 repo Anda dan hanya dapat dilihat oleh pengguna alur kerja.

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 alur kerja, pastikan Anda memiliki:

• Salah satu Capgo dengan langganan aktif dan __CAPGO_KEEP_1__ Capgo API key
• Aplikasi Anda terdaftar di Capgo (jika belum)bunx @capgo/cli@latest app add Kredensial pembangun yang telah dikonfigurasi secara lokal dengan
• lihat — bunx @capgo/cli@latest build init __CAPGO_KEEP_0__ Pengelolaan Kredensial untuk panduan walkthrough sihir
• Sukses Membangun Lokal (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI bukan tempat untuk memperbaiki bangun pertama Anda
• The GitHub CLI (gh) terpasang dan terotentikasi (gh auth login)

Pesan

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

Pengaturan

Capgo CLI dapat mengexport kredential lokal Anda sebagai file yang siap digunakan. .env Kombinasikan ini dengan gh secret set -f, sehingga setup CI/CD menjadi tiga perintah — tidak ada pengaturan base64 manual, tidak ada pengaturan JSON, tidak ada menyalin-menyunting rahasia secara manual.

1. Tambahkan kunci Capgo API Anda sebagai rahasia repository

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

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   Generate kunci di dashboard Capgo dengan unggah __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ dapat mengexport kredential lokal Anda sebagai file yang siap digunakan. Kombinasikan ini dengan , sehingga setup CI/CD menjadi tiga perintah — tidak ada pengaturan base64 manual, tidak ada pengaturan JSON, tidak ada menyalin-menyunting rahasia secara manual. atau tingkat yang lebih tinggi.

2. Eksportkan kredential Anda ke sebuah .env file

   Jalankan manajer kredential 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, kedua rahasia platform akan berada di file yang sama di bawah # === IOS === dan # === ANDROID === Judul-judul bagian. Nama variabel lingkungan iOS dan Android terpisah, sehingga menggabungkannya tidak menimbulkan konflik.

   Perlu file per-platform?

   Ya --platform ios (atau --platform android) untuk membatasi manajer 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 manajer menemukan perbedaan, maka ia mencetak kunci-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 membutuhkan untuk memutar kredit — file ini bukanlah artefak yang berumur lama.

4. Buat file alur kerja

   Tambahkan .github/workflows/capgo-build.yml ke repositori Anda. Pilih salah satu dari tiga pola pengaktifan di bawah ini tergantung pada bagaimana Anda ingin mengaktifkan 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 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
(ditambahkan secara manual)	CAPGO_TOKEN

Anda tidak perlu mengingatnya — contoh alur kerja di bawah sudah mengacu pada semua hal tersebut.

Contoh Alur Kerja

Tiga contoh di bawah ini mencakup pola yang paling umum. Mereka semua menggunakan bentuk yang sama: cek repo, instal dependensi, bangun aset web, sinkron ke native, lalu panggil Capgo Bangun dengan kredit yang dikirim sebagai variabel lingkungan.

1. Trigger Manual

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

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

2. Rilis pada Tag

Membangun dan mengirimkan kedua platform secara bersamaan ketika Anda mendorong tag versi seperti v1.4.0. Ini adalah konfigurasi produksi paling umum — git tag v1.4.0 && git push --tags menjadi perintah rilis Anda.

github/aliran 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 bangunan iOS gagal tidak akan membatalkan bangunan 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 bangunan Anda setiap kali Anda melakukan rilis bangunan. Jika Anda lebih suka memasangkannya ke tag, lihat Tidak Bump Nomor Bangunan di bawah.

3. Bangunan Debug pada Push ke Utama

Mengatasi bangunan regresi native awal dengan menghasilkan bangunan debug Android pada setiap push ke utama mainMurah untuk dijalankan, feedback cepat, dan Anda dapat melompatkan upload Play Store untuk menjadikannya hanya tes asap.

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 pengiriman ke Play Store (tidak PLAY_CONFIG_JSON diperlukan), dan --output-upload menghasilkan URL download untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat tes.

Polosan Umum

Lompatkan Upload Play Store / TestFlight

Untuk bangunan 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 satunya dengan --output-upload untuk mendapatkan URL download sementara untuk file biner.

Pengiriman toko untuk tinjauan

Dengan default, bangunan rilis 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}"

Pengguna iOS menggunakan kunci jalur App Store Connect API 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

Jalur ini hanya mengirimkan artefak build. Metadata penjualan toko, kelompok tester, detail kontak tinjauan, jawaban kewenangan, dan pilihan peluncuran masih perlu disiapkan 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, lalu baca kembali di langkah-langkah berikutnya dengan build last-outputTidak ada pemindaian 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 cetak hanya URL download (dengan garis baru; aman untuk URL=$(...)).
• --field qrCodePngPath cetak jalur PNG sehingga Anda bisa mengunggahnya sebagai lampiran PR.
• --qr cetak kode QR ASCII yang telah dirender — letakkan di dalam pagar Markdown code di komentar PR untuk skanabilitas inline.

Catatan

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 diam-diam mengeluarkan URL kosong.

Skip meningkatkan 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 dependensi cache

bun install sudah cukup cepat sehingga cache dependensi JS jarang memberikan manfaat, tetapi Capacitor’s dependensi asli (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 masalah

Gejala	Penyebab yang mungkin
CAPGO_TOKEN is not set	Tidak ada rahasia yang ditambahkan, atau pekerjaan tidak memiliki akses ke itu (periksa proteksi lingkungan/ cabang)
Kesalahan kredential 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 berhasil di lokal	Plugin asli tidak ada di package.json, atau kamu 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 lokal dengan bunx @capgo/cli@latest build credentials manage
Pembangunan berhenti setelah "Mengunggah proyek"	Arsip proyek tidak biasa besar — periksa bahwa node_modules tidak sedang diunggah (tidak seharusnya secara default)
Provisioning profile doesn't match bundle ID	Peta pengaturan menunjuk ke ID paket yang berbeda daripada yang Xcode tandatangani. Jalankan ulang build init untuk memperbarui profil, kemudian kembali kelexport dengan build credentials manage
Kredensial berubah secara lokal tetapi CI masih gagal	Jangan lupa untuk kembali kelexport dan kembali kepush: bunx @capgo/cli@latest build credentials manage → gh secret set -f .env.capgo.<appId>
Pengelola menolak menulis file kombinasi	Kunci konfigurasi bersama berbeda antar platform — pengelola memberi peringatan dan meminta konfirmasi. Atau konfirmasi untuk menggantikan satu-satunya, atau kembali kelexport 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 ditambahkan null ke 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 rekaman. Pastikan baik produsen maupun 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 gagal bangun platform khusus, lihat Petunjuk Perbaikan.

Langkah Selanjutnya

Auto OTA atau Native Branch CI antara update live upload dan Capgo Build.

Trigger dari UI CI Jalankan Capgo Build dari tab Aksi secara on demand.

Membangun Webhooks Mulai aliran kerja yang sama dari panggilan HTTP dashboard admin.

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

Pilihan Konfigurasi Semua CLI flag dan variabel lingkungan untuk menyesuaikan build Anda.