Aksi GitHub

Salin prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

Mengautomasi pembangunan iOS dan Android 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 untuk disimpan — tanpa ada anggota tim yang perlu Mac, Xcode, atau Android Studio terinstal.

Apa yang Anda Dapatkan

Rilis Tangan Kosong

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

Tidak Perlu 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 repository GitHub rahasia, terbatas pada repositori Anda dan hanya dapat dilihat oleh pengguna aliran.

Bangun Paralel

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

Persyaratan

Sebelum mengatur aliran, pastikan Anda memiliki:

Salah satu Capgo dengan langganan aktif dan __CAPGO_KEEP_1__ kunci __CAPGO_KEEP_1__ Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add Sebelum mengatur aliran, pastikan Anda memiliki:
Membuat kredensial yang telah dikonfigurasi secara lokal dengan bunx @capgo/cli@latest build init — lihat Pengelolaan Kredensial untuk panduan langkah demi langkah dari wizard
Suatu build lokal yang sukses (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — CI bukanlah tempat untuk memperbaiki build pertama Anda
The GitHub CLI (gh) terpasang dan terotentikasi (gh auth login)

Setup

The Capgo CLI can export your local credentials as a ready-to-use .env File __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ dapat mengekspor kredit lokal Anda sebagai file yang siap digunakan. gh secret set -fFile ini dikombinasikan dengan

Add your Capgo API key as a repository secret

Tambahkan kunci API __CAPGO_KEEP_1__ Anda sebagai rahasia repository
Kunci __CAPGO_KEEP_0__ ini tidak termasuk dalam penyimpanan kredit per aplikasi, sehingga tambahkan secara manual:
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Salin ke clipboard Generate kunci di dashboard Capgo bersama dengan unggah atau hak akses yang lebih tinggi.
Export kredit Anda ke sebuah .env file

Jalankan manajer kredit interaktif:
Jendela terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Pada TUI, pilih Export ke .env. File CLI ini .env.capgo.<appId> ditulis ke direktori saat ini dengan mode 0600 (hanya dapat dibaca oleh pemilik repository) — misalnya, .env.capgo.com.example.app. Ketika kedua iOS dan Android dikonfigurasi, rahasia kedua platform akan 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.

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

Apa yang perlu diatur untuk setiap platform (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) dapat disimpan secara independen dan mungkin telah berbeda-beda. 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-export dengan --platform jika Anda perlu menyimpan nilai per-platform.
Pilih file untuk .env dimasukkan ke rahasia Actions GitHub.

Perintah gh secret set -f membaca file dotenv dan membuat rahasia repository satu per KEY=value baris:
Jendela terminal
```
gh secret set -f .env.capgo.com.example.app
```
Itu saja — semua rahasia yang dibutuhkan oleh alur kerja Anda sekarang ada di GitHub. Verifikasi dengan gh secret list.
Dilarang mengkomit file .env
It berisi bahan tanda tangan plaintext. Setelah Anda telah meneruskannya ke GitHub:
Jendela terminal
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Re-export kapan saja Anda perlu memutar kredit — file ini bukanlah artefak yang berumur panjang.
Buat file aliran 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 memicu pembangunan.

Apa yang berakhir di bagian rahasia Anda

Sebagai referensi, gh secret set -f Akan membuat rahasia repositori ini (YAML aliran kerja Anda merujuk 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`
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 sudah mengacu semua dari mereka.

Contoh Aliran Kerja

Tiga contoh di bawah ini menangani 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.

1. Trigger Manual

Mengizinkan siapa pun dengan akses tulis untuk menyalakan bangun dari Aksi Tab di GitHub dengan dropdown platform. Bermanfaat untuk membuat build ad-hoc atau memulai rilis secara on demand.

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, kunjungi Aksi → Capgo Build (Manual) → Jalankan workflow untuk mengaktifkannya.

2. Rilis pada Tag

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

Matrix berjalan 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. Bangun Debug pada Kirim ke Utama

Mengatasi kembali masalah build asli dengan cepat dengan menghasilkan build Android debug pada setiap push ke main. Murah untuk dijalankan, feedback cepat, dan Anda dapat melewatkan proses unggah ke Play Store untuk menjadikannya tes asap 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-upload

Bagian paths filter memastikan aliran kerja tidak berjalan pada perubahan dokumen saja. --no-playstore-upload melewatkan proses unggah ke Play Store (tidak PLAY_CONFIG_JSON diperlukan), dan --output-upload menghasilkan URL download untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat tes.

Polanya Umum

Skip Unggah Toko Play / 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.

Unggah rilis toko untuk tinjauan

Dengan default, rilis upload file yang ditandatangani dan meninggalkan aksi toko akhir di bawah kendali Anda. Untuk rilis CI yang harus langsung masuk ke 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 jalur produksi secara default dengan release_status: completed. Lebih baik menyebutkan jalur pada situs panggilan dengan --android-track (atau PLAY_STORE_TRACK), dan override status dengan --android-release-status / PLAY_STORE_RELEASE_STATUS ketika dibutuhkan:

- 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 kunci jalur App Store Connect API dan mengirimkan build yang diproses ke tinjauan App Store. Ini memerlukan app_store distribusi; --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

Baca URL keluaran pembangunan dan QR code

Sukses --output-record <path> untuk menyimpan URL artefak pembangunan dan QR code ke disk ketika pembangunan berhasil, kemudian membacanya 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, 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 baris baru; aman untuk URL=$(...)).
--field qrCodePngPath Mencetak jalur PNG sehingga Anda bisa mengunggahnya sebagai lampiran PR.
--qr Mencetak kode QR ASCII yang telah di-render — masukkan ke dalam pagar Markdown code di komentar PR untuk skanabilitas inline.

Catatan

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

Ketergantungan Cache

bun install Cache ketergantungan sudah cukup cepat sehingga cache JS-deps jarang memberikan manfaat, tapi ketergantungan asli Capacitor (CocoaPods, Gradle) patut 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

: Halaman/Areas: Halaman Bantuan / halaman bantuan premium atau bagian bantuan di footer. Peran: Judul bagian atau halaman. Dilihat di: halaman support-policy.astro. Kunci pesan `support_policy_troubleshooting_title` (Judul Pengaturan Bantuan)	Judul Bagian “Pengaturan”
`CAPGO_TOKEN is not set`	Gejala
Penyebab yang mungkin	`gh secret set -f` Kunci rahasia tidak ditambahkan, atau pekerjaan tidak memiliki akses ke rahasia tersebut (periksa perlindungan lingkungan/ cabang) `gh secret list`
`cap sync` Ketergantungan iOS / Android hilang eror-nya tidak berjalan, atau tidak berjalan terhadap repositori yang berbeda. Verifikasi dengan menggunakan ‘was not run, or was run against a different repo. Verify with’ ‘fails in CI but works locally’	A plugin asli tidak ada `package.json`, atau kamu lupa `bun install` sebelumnya `cap sync`
Tidak ada plugin asli, atau kamu lupa	atau kamu lupa `bunx @capgo/cli@latest build credentials manage`
sebelum	Build berhasil tetapi aplikasi tidak muncul di App Store Connect `node_modules` ID tim salah, atau aplikasi rekaman belum ada di App Store Connect. Pastikan secara lokal dengan
`Provisioning profile doesn't match bundle ID`	Build terhambat setelah "Mengunggah proyek" `build init` Arsip proyek sangat besar — periksa bahwa `build credentials manage`
tidak sedang diunggah (tidak seharusnya secara default)	Map provisi mengarah ke ID paket yang berbeda daripada yang Xcode tandatangani. Jalankan ulang untuk memperbarui profil, kemudian re-export dengan `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. 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-upload`atau gagal sebelum menghasilkan artefak. `outputUrl` Akan `null` tercatat. Cabang pada `[ -n "$URL" ]` sebelum menggunakan
`build last-output` terjadi dengan `Unsupported record schemaVersion`	Penggunaan runner 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

For platform-specific build failures, lihat panduan Panduan Penyelesaian Masalah.

Langkah Selanjutnya

Auto OTA atau Native Branch CI between live update upload and Capgo Build.

Trigger dari CI UI Run Capgo Build from the Actions tab on demand.

Webhook Pembangunan Mulai alur kerja yang sama dari panggilan HTTP dashboard admin.

Pengaturan Kredensial Panduan lengkap untuk mempersiapkan kredential iOS dan Android sebagai rahasia base64.

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