GitHub Aksi

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

Apa yang Anda Dapatkan

Rilis Tangan Kosong

Tagkan rilis di Git dan file biner iOS dan Android yang ditandatangani akan dikirimkan ke TestFlight dan Play Store secara otomatis.

Tidak Ada Pengaturan Lokal

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

Rahasia Terbatas

Kredensial hidup di GitHub rahasia repository, terbatas pada repositori Anda dan hanya dapat dilihat oleh pengguna aliran. Mudah untuk memutar, mudah untuk memeriksa.

Pembangunan Paralel

Buat iOS dan Android secara bersamaan dengan pekerjaan matrix. Rilis biasanya selesai dalam waktu kurang dari 10 menit.

Persyaratan

Pastikan Anda telah memiliki:

• Akun Capgo dengan langganan aktif dan kunci __CAPGO_KEEP_1__ Capgo API key
• Your app registered in Capgo (bunx @capgo/cli@latest app add Kredensial build dikonfigurasi secara lokal dengan
• — lihat bunx @capgo/cli@latest build init Manajemen Kredensial untuk walkthrough sihir Build lokal berhasil (
• ) — CI bukanlah tempat untuk memperbaiki build pertama Andabunx @capgo/cli@latest build request com.example.app --platform android --build-mode debugThe
• A GitHub CLI (gh) terpasang dan terotentikasi (gh auth login)

Catatan

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 ini menghandle pembuatan sertifikat, profil pengembang, keystore, dan akun layanan Play Store secara interaktif.

Pengaturan

Capgo CLI dapat mengexport kredensial lokal Anda sebagai file yang sudah siap digunakan. .env Kombinasikan ini dengan gh secret set -f, sehingga setup CI/CD seluruhnya menjadi tiga perintah — tidak ada pengkodean base64 manual, tidak ada penggabungan JSON, tidak ada salinan-pasang rahasia-rahasia.

1. Tambahkan kunci Capgo API Anda sebagai rahasia repository

   The API tidak termasuk dalam penyimpanan kunci aplikasi per-app, jadi tambahkan secara manual:

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   Generate kunci di Capgo dashboard dengan upload izin atau lebih tinggi.

2. Export kredential Anda ke .env file

   Jalankan manajer kredential interaktif:

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

   Di TUI, pilih Eksport ke .env. File CLI ditulis .env.capgo.<appId> ke direktori saat ini dengan mode 0600 (hanya dapat dibaca oleh pemilik) — misalnya, .env.capgo.com.example.app. Ketika kedua iOS dan Android sudah terkonfigurasi, kedua platform's rahasia berada di file yang sama di bawah # === IOS === dan # === ANDROID === judul bagian. Nama variabel lingkungan iOS dan Android berbeda, sehingga menggabungkannya tidak akan menimbulkan konflik.

   Perlu file per platform?

   Lalui --platform ios (atau --platform android) untuk menentukan pengelola ke satu platform. Ekspor kemudian 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 toggle konfigurasi (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) dapat disimpan di bawah masing-masing platform secara independen dan mungkin telah berbeda. Jika pengelola menemukan perbedaan, maka akan mencetak kunci yang bertentangan, meminta konfirmasi eksplisit sebelum menulis, dan menyematkan daftar konflik sebagai komentar di atas file. Re-ekspor dengan --platform jika Anda perlu mempertahankan nilai per-platform.

3. Pindahkan file .env ke GitHub Rahasia Aksi

   Perintah gh secret set -f membaca file dotenv dan membuat rahasia repositori satu per KEY=value baris:

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

   Itu saja — semua rahasia alur kerja Anda sekarang ada di GitHub. Verifikasi dengan gh secret list.

   Jangan komit file .env

   File tersebut berisi bahan tanda tangan plaintext. Setelah Anda telah memasukkannya ke GitHub:

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

   Re-export kapan saja Anda membutuhkan untuk memutar kredit — file tersebut bukanlah artefak yang berumur lama.

4. Buat file alur kerja

   Tambah .github/workflows/capgo-build.yml ke repository Anda. Pilih salah satu pola trigger di bawah ini tergantung bagaimana Anda ingin memicu pembangunan.

Apa yang berakhir di rahasia Anda

Untuk referensi, gh secret set -f akan membuat rahasia repository ini (YAML workflow 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
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 workflow di bawah ini sudah mengacu semua dari mereka.

Contoh Workflow

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

2. Pengaktifan Manual

Aksi tab di __CAPGO_KEEP_0__ dengan dropdown platform. Berguna untuk tes ad-hoc atau memulai rilis secara on demand. .GitHub/workflows/__CAPGO_KEEP_1__-build-manual.yml

.github/workflows/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 }}

dengan ID aplikasi Anda. Setelah di-commit, pergi ke com.example.app Aksi → __CAPGO_KEEP_0__ Bangun (Manual) → Jalankan alur kerja Actions → Capgo Build (Manual) → Run workflow untuk mengaktifkannya.

2. Rilis pada Tag

Membangun dan mengirimkan kedua platform secara paralel setiap kali Anda mendorong tag versi seperti v1.4.0Pengaturan 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

Matrix menjalankan iOS dan Android secara paralel di runner yang terpisah. Mengatur 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 secara otomatis meningkatkan nomor build pada setiap rilis build. Jika Anda lebih suka menempelkannya ke tag, lihat Skip meningkatkan nomor build di bawah.

3. Debug Build pada Push ke Utama

Mengatasi kembali kinerja build asli awal dengan menghasilkan build Android debug pada setiap push ke main. Murah untuk dijalankan, feedback cepat, dan Anda dapat melewatkan unggah ke 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

Filter paths menyebabkan aliran kerja tidak berjalan pada perubahan dokumen hanya. --no-playstore-upload skips Pengiriman Toko Play (tidak PLAY_CONFIG_JSON diperlukan), dan --output-upload menghasilkan URL download untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat tes.

Polosan Umum

Lewatkan Pengiriman Toko Play / Uji Coba Terbang

Untuk build tes, lewati pengiriman ke 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 yang berlaku waktu terbatas untuk file biner.

Baca URL output build dan QR code

Pass --output-record <path> untuk menyimpan URL artefak pembangunan dan QR code ke disk ketika pembangunan berhasil, kemudian baca kembali di langkah-langkah berikutnya tanpa memerlukan scraping log atau regex. build last-outputSalin ke clipboard

- 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 ) dan sebuah QR PNG __CAPGO_KEEP_0__ di sampingnya di jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) and a PNG QR code alongside at /tmp/build.json.qr.png. build last-output mencetak hanya URL download (dipisahkan oleh newline; aman untuk

• --field outputUrl mencetak jalur PNG sehingga Anda dapat mengunggahnya sebagai lampiran PR. URL=$(...)).
• --field qrCodePngPath mencetak QR ASCII yang telah dirender — letakkan di dalam pagar Markdown __CAPGO_KEEP_0__ di komentar PR untuk skanabilitas inline.
• --qr prints the rendered ASCII QR — drop it inside a Markdown code fence on the PR comment for inline scannability.

Perlu diingat

Catatan hanya ditulis pada sukses build. schemaVersion Tidak Dapat Dibantu --field values exit non-zero, so a stale CLI in the runner fails loudly instead of silently emitting an empty URL.

nilai keluar non-nol, jadi __CAPGO_KEEP_0__ dalam runner gagal keras bukan diam dengan mengeluarkan URL kosong.

Bagian berjudul “Lewatkan peningkatan nomor build” --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

Salin ke clipboard

bun install is already fast enough that a JS-deps cache rarely pays off, but Capacitor’s native dependencies (CocoaPods, Gradle) are worth caching for larger projects:

- 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	Anda tidak menambahkan rahasia, atau pekerjaan tidak memiliki akses ke rahasia tersebut (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 Anda lupa bun install sebelum cap sync
Pembangunan berhasil tetapi tidak ada aplikasi yang muncul di App Store Connect	ID tim yang salah, atau catatan aplikasi belum ada di App Store Connect. Periksa secara lokal dengan bunx @capgo/cli@latest build credentials manage
Proses build terhenti setelah "Mengunggah proyek"	Arsip proyek terlalu besar — periksa bahwa node_modules tidak sedang diunggah (hal itu tidak seharusnya secara default)
Provisioning profile doesn't match bundle ID	Peta provisi mengarah ke ID paket yang berbeda daripada yang Xcode sedang menandatangani. Jalankan build init untuk memperbarui profil, kemudian re-export dengan build credentials manage
Kredensial berubah secara lokal tetapi CI masih gagal	Jangan 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. Atau konfirmasi untuk menggantikan satu-satunya, atau re-export per-platform dengan --platform ios / --platform android
build last-output mencetak URL kosong	Proses build tidak berhasil --output-uploadatau gagal sebelum menghasilkan artefak. outputUrl akan menjadi null dalam catatan. Cabang pada [ -n "$URL" ] sebelum menggunakan itu
build last-output salah dengan Unsupported record schemaVersion	Jalankan adalah pada versi lebih tua CLI daripada yang menulis catatan. Pin baik produsen dan pembaca ke versi eksplisit yang sama (misalnya bunx @capgo/cli@7.104.0 … pada kedua sisi) daripada @latest, yang mengapung dan dapat berubah-ubah antar pekerjaan

Untuk gagal bangunan spesifik platform, lihat Petunjuk Perbaikan.

Langkah-Langkah Selanjutnya

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

Buat iOS Tuntunan yang lebih dalam tentang sertifikat, profil, dan pengiriman ke App Store.

Buat Android Pengaturan keystore, layanan akun Play Store, dan pengelolaan rasa.

Opsi Konfigurasi Semua CLI flag dan variabel lingkungan untuk memperhalus build Anda.