GitHub Aksi

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

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

Rahasia Terbatas

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

Pembangunan Paralel

Pembangunan iOS dan Android secara bersamaan dengan 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__ Capgo API key
Your app registered in Capgo (bunx @capgo/cli@latest app add jika belum)
Membuat kredit yang dikonfigurasi secara lokal dengan bunx @capgo/cli@latest build init — lihat Pengelolaan Kredit untuk panduan langkah demi langkah sihir
Sukses membangun lokal ('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) Menginstal dan terautentikasi (gh auth login)

Konfigurasi

The Capgo CLI can export your local credentials as a ready-to-use .env File ini dapat diekspor dari kredential lokal Anda dalam bentuk siap digunakan. gh secret set -fKombinasikan ini dengan

Add your Capgo API key as a repository secret

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

Jalankan manajer kredential 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 Anda dengan mode 0600 (hanya dapat dibaca oleh pemilik repository) — misalnya, .env.capgo.com.example.app. Ketika kedua iOS dan Android telah 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 pengelola 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.

A beberapa konfigurasi toggle (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) dapat disimpan di bawah setiap 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-export dengan --platform Jika Anda perlu menyimpan nilai per-platform.
Push file ke __CAPGO_KEEP_0__ Rahasia Aksi .env file to GitHub Actions secrets

Jendela terminal gh secret set -f Salin ke clipboard KEY=value Itu saja — setiap rahasia yang dibutuhkan oleh alur kerja Anda sekarang ada di __CAPGO_KEEP_0__. Verifikasi dengan
Tidak komit file .env
```
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.
Jangan komit file .env
It berisi bahan tanda tangan plaintext. Setelah Anda telah memasukkannya ke GitHub:
Jendela terminal
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Re-export kapan saja Anda membutuhkannya untuk memutar kredit — file ini bukanlah artefak yang berumur panjang.
Buat file workflow

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 workflow 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`
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 pada semua dari mereka.

Contoh Aliran 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, 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. Berguna untuk tes ad-hoc atau memulai rilis secara mandiri.

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

2. Rilis pada Tag

Membangun dan mengirimkan kedua platform secara paralel setiap kali Anda push 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

Matris menjalankan iOS dan Android secara paralel di runner yang terpisah. Pengaturan fail-fast: false berarti bahwa jika build iOS gagal, maka build Android yang sedang berlangsung tidak akan dibatalkan (dan sebaliknya) — berguna ketika salah satu platform mengalami masalah tanda tangan sementara.

3. Debug Build pada Push ke Main

Menangkap kembali gangguan 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 sebagai tes asap.

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 ini 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 download untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat tes.

Gaya Umum

Lebihkan Upload Toko / Uji Coba

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

Kirimkan 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 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 berlaku secara default pada jalur produksi 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 yang sudah selesai bukan 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, lalu 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 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 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 skannabilitas inline.

Bagian berjudul “Mengabaikan peningkatan nomor build”

Salin ke clipboard --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 Ketergantungan cache 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

Gejala	Penyebab yang mungkin
`CAPGO_TOKEN is not set`	Rahasia tidak ditambahkan, atau pekerjaan tidak memiliki akses ke rahasia (periksa proteksi lingkungan/ cabang)
Ketergantungan iOS / Android hilang	`gh secret set -f` Ran tidak dijalankan, atau dijalankan terhadap repositori yang berbeda. Periksa dengan `gh secret list`
`cap sync` Ran gagal di CI tetapi berhasil di lokal	A plugin asli tidak ada di `package.json`, atau Anda lupa `bun install` sebelum `cap sync`
Sebelum memulai bekerja pada fitur baru, buatlah isu dan diskusikan	Sebelum memulai bekerja pada fitur baru, sebutkan isu `bunx @capgo/cli@latest build credentials manage`
Pembangunan berhasil tetapi aplikasi tidak muncul di App Store Connect	ID tim salah, atau catatan aplikasi belum ada di App Store Connect. Verifikasi secara lokal dengan `node_modules` Pembangunan terhenti setelah "Mengunggah proyek"
`Provisioning profile doesn't match bundle ID`	Arsip proyek sangat besar — periksa bahwa `build init` tidak sedang diunggah (hal itu tidak seharusnya secara default) `build credentials manage`
Peta penyediaan mengarah ke ID paket yang berbeda dari 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>`
Manajer menolak menulis file kombinasi	Kunci 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 kosong	Pembangunan tidak berhasil `--output-upload`atau gagal sebelum menghasilkan artefak. `outputUrl` akan `null` dalam catatan. Cabang pada `[ -n "$URL" ]` sebelum menggunakan
`build last-output` terjadi kesalahan dengan `Unsupported record schemaVersion`	Pengguna menjalankan versi lama 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 mengambang dan dapat berubah-ubah antar pekerjaan

For gagal pembangunan platform tertentu, lihat panduan Panduan Penyelesaian Masalah.

Langkah Selanjutnya

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

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

Build Webhooks Mulai alur kerja yang sama dari panggilan HTTP dashboard admin.

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

Opsi Konfigurasi Tunjukkan semua CLI flag dan variabel lingkungan untuk mengoptimalkan build Anda.