GitHub Aksi

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

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

Apakah Anda Dapatkan

Pengiriman Tangan-Bebas

Tagkan rilis 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 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 audit.

Pembangunan Paralel

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

Persyaratan

Sebelum mengatur alur kerja, pastikan Anda memiliki:

Suatu Capgo akun dengan langganan aktif dan sebuah Capgo API kunci
Aplikasi Anda terdaftar di Capgo (bunx @capgo/cli@latest app add jika tidak)
Kredensial pembangunan dikonfigurasi secara lokal dengan bunx @capgo/cli@latest build init — lihat Manajemen Kredensial untuk walkthrough sihir
Suatu pembangunan lokal 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)

Pengaturan

The Capgo CLI dapat mengexport kredensial lokal Anda sebagai file yang siap digunakan, .env file. Digabungkan dengan gh secret set -fMengubah seluruh pengaturan CI/CD menjadi tiga perintah — tidak ada pengkodean base64 manual, tidak ada pengaturan JSON, tidak ada menyalin-menyimpan rahasia secara manual.

Tambahkan kunci Capgo API Anda sebagai rahasia repository.

Kunci API bukanlah bagian dari penyimpanan kunci per aplikasi, jadi tambahkan secara manual:
Jendela terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Generate kunci di Dashboard Capgo dengan upload izin atau lebih tinggi.
Export kredential Anda ke .env file

Jalankan pengelola kunci interaktif:
Jendela terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
Pada TUI, pilih Export ke .env. File 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.

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

Beberapa toggle konfigurasi (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 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

Perintah membaca file dotenv dan membuat rahasia repository satu per baris: gh secret set -f Jendela terminal KEY=value Salin ke clipboard
Itu saja — setiap rahasia yang dibutuhkan oleh alur kerja Anda sekarang ada di __CAPGO_KEEP_0__. Verifikasi dengan
```
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.
Jendela terminal
It contains plaintext signing material. Once you’ve pushed it to GitHub:
Re-export kapan saja Anda membutuhkan untuk memutar kredential — file ini bukanlah artefak yang berumur lama.
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Salin ke clipboard
Membuat file aliran kerja

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

Apa yang berakhir di rahasia Anda

Sebagai referensi, gh secret set -f akan membuat rahasia repositori berikut (YAML kerja aliran 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`
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 ini sudah mengacu pada semua hal tersebut.

Contoh Aliran 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, kemudian 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 bangun ad-hoc atau memulai rilis sesuai permintaan.

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 komit, pergi ke Aksi → Capgo Bangun (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.0Ini 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 menjalankan iOS dan Android secara paralel di runner yang terpisah. Mengatur fail-fast: false berarti bangun iOS gagal tidak akan membatalkan bangun 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 asli dengan cepat 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 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

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

Lewatkan pengiriman ke Play Store / Uji Coba TestFlight

Untuk build uji, lewatkan pengiriman ke toko: Android menggunakan

(yang tidak pernah mengirimkan ke App Store). Gabungkan salah satunya dengan --no-playstore-uploadmelewatkan pengiriman ke App Store --ios-distribution ad_hoc untuk build uji --output-upload Mendapatkan URL download sementara untuk file biner.

Baca URL output pembangunan dan QR code.

Simpan --output-record <path> Mendapatkan URL download sementara untuk file biner dan QR code ketika pembangunan berhasil, kemudian 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 Menghasilkan catatan JSON (dengan jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) dan QR PNG code di /tmp/build.json.qr.png. build last-output Membaca kembali:

--field outputUrl Mencetak hanya URL download (dipisahkan oleh garis baru; aman untuk URL=$(...)).
--field qrCodePngPath Mencetak jalur PNG sehingga Anda dapat mengunggahnya sebagai lampiran PR.
--qr mencetak kode QR ASCII yang telah di-render — letakkan di dalam pagar Markdown code di komentar PR untuk skanabilitas inline.

Lompatkan 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

Mengarsipkan dependensi

bun install sudah cukup cepat sehingga cache dependensi JS jarang memberikan keuntungan, tapi dependensi native 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`	Kunci tidak ditambahkan, atau pekerjaan tidak memiliki akses ke itu (periksa proteksi lingkungan/ cabang)
Kesalahan kredential iOS / Android yang hilang	`gh secret set -f` dibutuhkan, atau Anda lupa `gh secret list`
`cap sync` Tidak dijalankan, atau dijalankan terhadap repositori yang berbeda. Verifikasi dengan	Gagal di CI tetapi berjalan di lokal `package.json`Plugin native tidak ada di”, atau Anda lupa `bun install` sebelumnya `cap sync`
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 `bunx @capgo/cli@latest build credentials manage`
Pembangunan terhenti 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 provisi mengarah ke ID paket yang berbeda daripada yang Xcode sedang menandatangani. Re-run `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 yang menang, 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 ditetapkan `null` dalam catatan. Cabang pada `[ -n "$URL" ]` sebelum menggunakan
`build last-output` terdapat kesalahan dengan `Unsupported record schemaVersion`	Pengguna adalah pada versi lama CLI dari yang 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 antar pekerjaan

Untuk gagal pembangunan spesifik platform, lihat panduan Panduan Penyelesaian Masalah.

Langkah-Langkah Selanjutnya

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

Buat iOS Petunjuk lebih lanjut 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 menyesuaikan build Anda.