GitHub Aksi

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

Automasi pembangunan iOS dan Android Anda secara 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 dan siap disimpan — tanpa ada anggota tim yang perlu memiliki Mac, Xcode, atau Android Studio terinstal.

What You Get

Tangani Rilis Otomatis

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

Tidak Perlu Konfigurasi Lokal

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

Rahasia Terbatas

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

Pembangunan Paralel

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

Persyaratan Sebelumnya

Sebelum mengatur alur kerja, pastikan Anda 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 pembangunan dikonfigurasi secara lokal dengan
— lihat bunx @capgo/cli@latest build init Manajemen Kredensial untuk walkthrough sihir Pembangunan lokal sukses (
) — CI bukanlah tempat untuk memperbaiki build pertama Andabunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug__CAPGO_KEEP_0__
The GitHub CLI (gh) terpasang dan terotentifikasi (gh auth login)

Setup

The Capgo CLI dapat mengexport kredensial lokal Anda sebagai file yang sudah siap digunakan. .env Dibandingkan dengan gh secret set -f, ini mengubah seluruh pengaturan CI/CD menjadi tiga perintah — tidak ada pengkodean base64 manual, tidak ada pengaturan JSON, tidak ada salinan-pengganti rahasia secara manual.

Tambahkan kunci Capgo API sebagai rahasia repository

Kunci API bukanlah bagian dari penyimpanan kredensial per-aplikasi, jadi tambahkan secara manual:
Jendela terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Buatlah kunci di dashboard Capgo dashboard hak upload atau lebih tinggi. Eksport kredential Anda ke file
Jalankan manajer kredential interaktif: .env __CAPGO_KEEP_0__

__CAPGO_KEEP_1__
Jendela terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Dalam TUI, pilih Eksport ke .envFile CLI menulis .env.capgo.<appId> ke direktori saat ini dengan mode 0600 Hanya dapat dibaca oleh pemilik — misalnya, .env.capgo.com.example.appKetika kedua iOS dan Android telah dikonfigurasi, rahasia kedua platform berada di file yang sama di bawah # === IOS === dan # === ANDROID === Judul bagian. Nama variabel lingkungan iOS dan Android berbeda, sehingga menggabungkannya tidak menimbulkan konflik.

Mengalihkan --platform ios (atau --platform android) untuk menentukan manajer 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.

Beberapa toggle konfigurasi (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) dapat disimpan di bawah platform yang berbeda secara independen dan mungkin telah berbeda. Jika manajer 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 mempertahankan nilai per-platform.
Pindahkan file .env ke GitHub Rahasia Aksi

Rahasia gh secret set -f Perintah membaca file dotenv dan membuat rahasia repository satu per baris: KEY=value Jendela terminal
Salin ke clipboard
```
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 ini berisi materi tanda tangan plaintext. Setelah Anda telah memasukkannya ke __CAPGO_KEEP_0__:
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Salin ke clipboard
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Buat file workflow
Jendela terminal

Tambahkan ke repositori Anda. Pilih salah satu pola trigger di bawah ini tergantung pada bagaimana Anda ingin menjalankan build. .github/workflows/capgo-build.yml Apa yang akhirnya masuk ke rahasia Anda

Buat rujukan,

Platform gh secret set -f Rahasia yang dibuat

iOS	Andoid
(ditambahkan secara manual)	`BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `CAPGO_IOS_PROVISIONING_MAP_BASE64`, `APPLE_KEY_ID`, `APPLE_ISSUER_ID`, `APPLE_KEY_CONTENT`, `APP_STORE_CONNECT_TEAM_ID`
Anda tidak perlu mengingatnya — contoh workflow di bawah sudah mengacu ke semua dari mereka.	`ANDROID_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
Tambahkan ke repositori Anda.	`CAPGO_TOKEN`

Pilih salah satu pola trigger di bawah ini tergantung pada bagaimana Anda ingin menjalankan build.

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

1. Trigger Manual

Mengizinkan siapa pun dengan akses tulis untuk memicu bangun dari Actions tab di GitHub dengan dropdown platform. Berguna untuk tes 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 di-commit, pergi ke Aksi → Capgo Build (Manual) → Jalankan alur kerja 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.

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.

3. Debug Build pada Push ke Utama

Mengatasi kembali regresi build native awal dengan menghasilkan build Android debug pada setiap push ke mainMurah untuk dijalankan, feedback cepat, dan Anda dapat melewatkan unggah ke Play Store untuk menjadikannya hanya 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

Ringkasan paths filter memastikan aliran kerja tidak berjalan pada perubahan dokumen saja. --no-playstore-upload melewatkan pengiriman ke Play Store (tidak perlu), dan PLAY_CONFIG_JSON menghasilkan URL download untuk APK hasilnya sehingga Anda dapat menginstalnya pada perangkat uji. --output-upload Polanya Umum

Judul Bagian “Polanya Umum”

Judul Bagian “Melewati Pengiriman ke Play Store / Uji Coba TestFlight”

; untuk iOS, bangun dalam mode ad-hoc dengan --no-playstore-upload(yang tidak pernah mengirimkan ke App Store). Gabungkan salah satu dengan --ios-distribution ad_hoc untuk mendapatkan URL download yang berlaku selama waktu tertentu untuk file biner. --output-upload filter memastikan aliran kerja tidak berjalan pada perubahan dokumen saja.

Mengirimkan rilis toko untuk tinjauan

Secara default, rilis yang dibangun mengunggah artifact 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 Mengirimkan 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 uses the App Store Connect API key path and submits the processed TestFlight build to App Store review. It requires app_store tidak wajib untuk distribusi beta eksternal dan tidak diperlukan untuk tinjauan App Store: --ios-testflight-groups Mengirimkan ke clipboard

- 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 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 catatan JSON (dengan jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) dan sebuah QR code PNG di sampingnya: /tmp/build.json.qr.png. build last-output membacanya kembali:

--field outputUrl prints hanya URL download (baris baru; aman untuk URL=$(...)).
--field qrCodePngPath prints jalur PNG sehingga Anda bisa mengunggahnya sebagai lampiran PR.
--qr prints kode QR ASCII yang telah dirender — masukkan ke dalam pagar Markdown code di komentar PR untuk skannabilitas inline.

Skip peningkatan nomor build

Dengan default setiap build rilis meningkatkan nomor build. Untuk mematikan nilai tersebut Anda kendalikan (misalnya, tag Git), kirimkan --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

Dependensi Cache

bun install Sudah cukup cepat sehingga cache dependensi JS jarang memberikan keuntungan, tetapi dependensi native 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 Masalah

Gejala	Penyebab yang Mungkin
`CAPGO_TOKEN is not set`	Kunci tidak ditambahkan, atau pekerjaan tidak memiliki akses ke itu (periksa proteksi lingkungan/ cabang)
Kesalahan kredential iOS / Android yang Hilang	`gh secret set -f` Tidak pernah dijalankan, atau dijalankan terhadap repositori yang berbeda. Verifikasi dengan `gh secret list`
`cap sync` Gagal di CI tetapi berhasil di lokal	A plugin asli tidak ada di sini `package.json`, atau kamu lupa `bun install` sebelumnya `cap sync`
Pembangunan berhasil tetapi tidak ada aplikasi yang muncul di App Store Connect	ID tim salah, atau catatan aplikasi belum ada di App Store Connect. Verifikasi secara lokal dengan `bunx @capgo/cli@latest build credentials manage`
Pembangunan terus-menerus setelah "Mengunggah proyek"	Arsip proyek sangat besar — cek 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. Coba lagi `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 bertanya 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` mengalami kesalahan dengan `Unsupported record schemaVersion`	Pengguna adalah pada versi lama CLI 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 mengapung dan dapat berubah-ubah antara pekerjaan

Untuk gagal bangun platform khusus, lihat panduan Panduan Penyelesaian Masalah.

Langkah-Langkah Selanjutnya

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

Bangun iOS Petunjuk yang lebih dalam tentang sertifikat, profil, dan pengiriman App Store.

Bangun Android Pengaturan kunci rahasia, layanan akun Play Store, dan pengelolaan rasa.

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