Trigger Native Build via Webhook
Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.
Capgo Build biasanya dimulai dari laptop atau job CI. Tim yang merilis dari dashboard admin, CMS, atau portal internal sering menginginkan satu webhook HTTP: tekan tombol di UI mereka sendiri, dan native build yang ditandatangani akan dimulai. Panduan ini menunjukkan pola standar — panggilan HTTP terautentikasi tipis ke host code Anda, yang menjalankan alur kerja Capgo Build yang sama yang sudah Anda gunakan.
Arsitektur
Bagian berjudul “Arsitektur”sequenceDiagram participant Admin as Admin dashboard participant Hook as Webhook endpoint participant CI as GitHub / GitLab participant Capgo as Capgo Build Admin->>Hook: POST /native-build (secret) Hook->>CI: repository_dispatch / pipeline trigger CI->>CI: checkout, npm ci, cap sync CI->>Capgo: build request Capgo-->>CI: signed binary / store upload
Anda tidak perlu mengekspos “build webhook” publik di Capgo. CI Anda sudah memiliki signing secrets; tugas webhook hanyalah memulai job CI tersebut dengan aman.
Prerequisites
Bagian berjudul “Prasyarat”- Workflow Build Capgo yang sudah berjalan dari UI CI atau saat push (Aksi GitHub)
- Izin untuk membuat token GitHub fine-grained, GitLab trigger token, atau yang setara
- Shared secret yang akan dikirim oleh admin dashboard Anda (header atau body)
Opsi A — GitHub repository_dispatch (direkomendasikan)
Bagian berjudul “Opsi A — GitHub repository_dispatch (direkomendasikan)”GitHub menerima panggilan API terautentikasi yang memulai workflow untuk mendengarkan repository_dispatch. Dashboard apa pun yang bisa POST JSON bisa memicunya.
1. Workflow yang mendengarkan webhook
Bagian berjudul “1. Workflow yang mendengarkan webhook”Validasi payload sebelum checkout dan sebelum langkah yang mengandung secret. Teruskan nilai yang diterima melalui job outputs / env vars — jangan pernah diinterpolasi client_payload langsung ke dalam run: scripts (panduan script injection).
name: Capgo Build (Webhook)
on: repository_dispatch: types: [capgo-native-build]
jobs: validate: runs-on: ubuntu-latest outputs: platform: ${{ steps.check.outputs.platform }} mode: ${{ steps.check.outputs.mode }} ref: ${{ steps.check.outputs.ref }} platforms_json: ${{ steps.check.outputs.platforms_json }} steps: - id: check env: RAW_PLATFORM: ${{ github.event.client_payload.platform }} RAW_MODE: ${{ github.event.client_payload.mode }} RAW_REF: ${{ github.event.client_payload.ref }} DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} run: | PLATFORM="${RAW_PLATFORM:-android}" MODE="${RAW_MODE:-release}" REF="${RAW_REF:-$DEFAULT_BRANCH}" case "$PLATFORM" in ios|android|both) ;; *) echo "Invalid platform: $PLATFORM" >&2; exit 1;; esac case "$MODE" in debug|release) ;; *) echo "Invalid mode: $MODE" >&2; exit 1;; esac # Allowlist branches / tags / full SHAs only if [[ ! "$REF" =~ ^(main|master|production|release/[A-Za-z0-9._-]+|[0-9a-f]{40})$ ]]; then echo "Ref not allowlisted: $REF" >&2 exit 1 fi if [ "$PLATFORM" = "both" ]; then PLATFORMS_JSON='["ios","android"]' else PLATFORMS_JSON=$(printf '["%s"]' "$PLATFORM") fi { echo "platform=$PLATFORM" echo "mode=$MODE" echo "ref=$REF" echo "platforms_json=$PLATFORMS_JSON" } >> "$GITHUB_OUTPUT"
build: needs: validate runs-on: ubuntu-latest environment: ${{ needs.validate.outputs.mode == 'release' && 'production' || 'build-debug' }} strategy: fail-fast: false matrix: platform: ${{ fromJSON(needs.validate.outputs.platforms_json) }} steps: - uses: actions/checkout@v4 with: ref: ${{ needs.validate.outputs.ref }}
- uses: actions/setup-node@v6 with: node-version: '24' cache: 'npm'
- run: npm ci - run: npm run build - name: Sync native project env: PLATFORM: ${{ matrix.platform }} run: npx cap sync "$PLATFORM"
- name: Capgo Build 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 }} 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 }} PLATFORM: ${{ matrix.platform }} MODE: ${{ needs.validate.outputs.mode }} run: | npx @capgo/cli@latest build request com.example.app \ --platform "$PLATFORM" \ --build-mode "$MODE"2. Buat token GitHub
Bagian berjudul “2. Buat token GitHub”Buat personal access token fine-grained (atau token instalasi GitHub App) dengan Isi: Read and write pada repository (wajib untuk repository_dispatch). Simpan hanya di admin backend Anda — jangan pernah di browser.
3. Panggil webhook dari dashboard admin Anda
Bagian berjudul “3. Panggil webhook dari admin dashboard Anda”Backend Anda (bukan browser pengguna akhir) harus mengirim:
curl -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer $GITHUB_TOKEN" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/dispatches \ -d '{ "event_type": "capgo-native-build", "client_payload": { "platform": "both", "mode": "release", "ref": "main", "requested_by": "admin@example.com" } }'| Kolom | Tujuan |
|---|---|
event_type | Harus cocok types di workflow (capgo-native-build) |
client_payload.platform | ios, android, atau both |
client_payload.mode | debug atau release |
client_payload.ref | Branch atau tag untuk build (opsional) |
Hubungkan JSON POST yang sama ke tombol di admin UI Anda (“Build native apps”). Dashboard hanya perlu mengakses URL backend; backend menyimpan GITHUB_TOKEN.
Opsi B — Tiny proxy webhook (host apa pun)
Bagian berjudul “Opsi B — Webhook proxy kecil (host apa pun)”Jika alat admin hanya bisa POST ke URL yang Anda kontrol (Zapier, Make, Cloudflare Worker, rute Express), letakkan proxy kecil di depan GitHub:
// Example Cloudflare Worker / Node handler (sketch)export default { async fetch(request, env) { if (request.method !== 'POST') { return new Response('Method not allowed', { status: 405 }) } if (request.headers.get('x-webhook-secret') !== env.WEBHOOK_SECRET) { return new Response('Unauthorized', { status: 401 }) } const body = await request.json().catch(() => ({})) const platform = body.platform || 'both' const mode = body.mode || 'release' const ref = body.ref || 'main' if (!['ios', 'android', 'both'].includes(platform)) { return new Response('Invalid platform', { status: 400 }) } if (!['debug', 'release'].includes(mode)) { return new Response('Invalid mode', { status: 400 }) } if (!/^(main|master|production|release\/[A-Za-z0-9._-]+|[0-9a-f]{40})$/.test(ref)) { return new Response('Ref not allowlisted', { status: 400 }) } const res = await fetch( `https://api.github.com/repos/${env.GITHUB_OWNER}/${env.GITHUB_REPO}/dispatches`, { method: 'POST', headers: { Accept: 'application/vnd.github+json', Authorization: `Bearer ${env.GITHUB_TOKEN}`, 'X-GitHub-Api-Version': '2022-11-28', }, body: JSON.stringify({ event_type: 'capgo-native-build', client_payload: { platform, mode, ref }, }), }, ) return new Response(res.status === 204 ? 'Build queued' : await res.text(), { status: res.status === 204 ? 200 : res.status, }) },}Lalu konfigurasikan produk admin:
| Pengaturan | Nilai |
|---|---|
| URL | https://your-worker.example.com/native-build |
| Metode | POST |
| Header | x-webhook-secret: <shared secret> |
| Body | { "platform": "both", "mode": "release" } |
Ini adalah bentuk umum untuk menghubungkan webhook ke dashboard admin: dashboard menyimpan satu URL dan satu secret; kredensial Capgo tetap di GitHub Actions.
Pemicu GitLab Pipeline
Bagian berjudul “GitLab Pipeline Trigger”GitLab menyediakan token pemicu pipeline yang merupakan target webhook alami.
# .gitlab-ci.yml fragmentcapgo_native_webhook: stage: build script: - npm ci && npm run build - npx cap sync "${PLATFORM:-android}" - npx @capgo/cli@latest build request com.example.app --platform "${PLATFORM:-android}" --build-mode "${BUILD_MODE:-release}" rules: - if: '$CI_PIPELINE_SOURCE == "trigger"'Buat trigger token di Pengaturan → CI/CD → Token pemicu pipeline, lalu dari backend admin:
curl -X POST \ -F token=$GITLAB_TRIGGER_TOKEN \ -F ref=main \ -F "variables[PLATFORM]=android" \ -F "variables[BUILD_MODE]=release" \ https://gitlab.com/api/v4/projects/PROJECT_ID/trigger/pipelineUntuk kedua platform, jalankan dua trigger atau perluas job menjadi matriks paralel dengan cara yang sama seperti contoh GitHub.
Bitbucket dan Azure
Bagian berjudul “Bitbucket dan Azure”| Platform | Mekanisme webhook |
|---|---|
| Bitbucket | URL pemicu pipeline atau custom pipeline + app password POST |
| Azure DevOps | REST API untuk run pipeline dengan PAT; gunakan pipeline manual dari Trigger dari UI CI |
Polanya identik: admin → pengecekan secret Anda → host API → Capgo Build job.
Checklist payload untuk admin tools
Bagian berjudul “Checklist Payload untuk Admin Tools”Saat membuat form dashboard, kumpulkan minimal:
- Platform — ios / android / keduanya
- Mode — debug (QA) atau release (store)
- Ref Git — branch atau tag yang akan di-build
- Aktor — email atau user id untuk audit log (teruskan
client_payload)
Opsional: setelah run selesai, minta CI mengirim balik ke admin API dengan URL download dari --output-record / build last-output.
Keamanan
Bagian berjudul “Keamanan”- Autentikasi setiap webhook (
x-webhook-secret, HMAC signature, atau mTLS). - Allowlist
platform,mode, danrefin both the proxy and the workflowvalidatejob — perlakukanclient_payloadsebagai input yang tidak tepercaya. - Lewatkan nilai yang diterima melalui env vars / job outputs; jangan interpolasi field payload ke dalam
run:scripts. - Simpan token GitHub/GitLab hanya di sisi server.
- Utamakan token yang cakupannya hanya satu repositori.
- Beri rate limit pada proxy; native build memakan build minutes.
- Untuk rilis yang di-submit ke store, petakan
releaseke Environment GitHub yang terlindungi (seperti pada contoh) atau wajibkan flag konfirmasi tambahan yang dicentang divalidate.