Mengaktifkan Pembangunan Asli melalui Webhook

Build Capgo biasanya dimulai dari laptop atau pekerjaan CI. Tim yang mengirimkan dari sebuah Papan Kontrol Admin, CMS, atau portal internal sering ingin memiliki satu Salinan untuk AI: press a button in their own UI, and a signed native build starts. This guide shows the standard pattern — a thin authenticated HTTP call into your code host, which runs the same Capgo Build workflow you already use.

Note

Capgo organisasi webhooks (Dashboard → Organisasi → Webhooks) menginformasikan anda tentang Capgo acara (bundel, saluran, anggota). Halaman ini adalah arah lain: anda system memanggil URL untuk memulai Capgo Build.

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 Capgo untuk mengungkapkan webhooks publik “build.” CI Anda sudah memiliki rahasia tanda tangan; tugas webhook hanyalah untuk memulai pekerjaan CI tersebut dengan aman.

Persyaratan

• Sebuah Capgo Workflow Build yang sudah berjalan dari awal dari UI CI atau pada push (GitHub Aksi)
• Ijin untuk membuat sebuah GitHub token yang halus, token trigger GitLab, atau setara
• Rahasia bersama yang dashboard admin akan kirim (header atau body)

Pilihan A — GitHub repository_dispatch (direkomendasikan)

GitHub menerima sebuah panggilan API yang terotentikasi yang memulai sebuah workflow yang mendengarkan repository_dispatchApapun dashboard yang bisa POST JSON bisa mengirimkannya.

1. Alur yang mendengarkan webhook

Validasi isi payload sebelum Checkout dan sebelum langkah apa pun yang mengandung rahasia. Masukkan nilai yang diterima ke dalam output pekerja / variabel lingkungan — tidak pernah interpolasi. client_payload langsung ke run: langsung kePetunjuk Penggunaan Injeksi Skrip).

/workflow/github/capgo-build-webhook.yml

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. Buatlah sebuah GitHub token

Buatlah token akses pribadi yang halus (atau token instalasi GitHub App) dengan Isi: Baca dan tulis pada repository (diperlukan untuk repository_dispatchSimpanlah hanya di backend admin Anda — tidak pernah di browser.

3. Panggil webhook dari dashboard admin Anda

Backend Anda (bukan browser pengguna) harus mengirimkan:

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"
    }
  }'

Bidang	Tujuan
event_type	Harus Sama types di dalam alur kerja (capgo-native-build)
client_payload.platform	ios, androidatau both
client_payload.mode	debug atau release
client_payload.ref	Branch atau tag untuk membangun (opsional)

Hubungkan JSON POST yang sama ke tombol di UI admin Anda ('Buat aplikasi native'). Dashboard hanya perlu mencapai your backend; backend tersebut menyimpan GITHUB_TOKEN.

Caution

Jangan menyematkan token GitHub di JavaScript frontend. Halaman admin harus memanggil server Anda; server Anda memanggil GitHub.

Option B — Proxy Webhook Mini (host mana saja)

Jika alat admin hanya dapat mengirim POST ke URL yang Anda kendalikan (Zapier, Make, Cloudflare Pekerja, Rute Express), letakkan proxy mini 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 konfigurasi produk admin:

Pengaturan	Nilai
URL	https://your-worker.example.com/native-build
Methode	POST
Kepala	x-webhook-secret: <shared secret>
Badan	{ "platform": "both", "mode": "release" }

Ini adalah bentuk biasa untuk menghubungkan webhook ke dashboard admin: dashboard menyimpan satu URL dan satu rahasia; Capgo kredit tetap di GitHub Aksi.

Trigger Pipa GitLab

GitLab mengungkapkan token trigger pipa yang merupakan target webhooks alami.

# .gitlab-ci.yml fragment
capgo_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 token trigger di bawah Pengaturan → CI/CD → Token trigger pipa, kemudian 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/pipeline

Untuk kedua platform, baiknya Anda mengaktifkan dua trigger atau memperluas pekerjaan menjadi matrix paralel dengan cara yang sama seperti contoh GitHub.

Bitbucket dan Azure

Platform	Mekanisme Webhook
Bitbucket	URL Trigger Pipa atau kata sandi pipa + aplikasi kustom POST
Azure DevOps	Jalankan Pipa REST API dengan PAT; gunakan pipa manual dari Trigger dari UI CI

Polanya identik: admin → cek rahasia Anda → host API → Capgo Tugas Bangun.

Daftar Checklist Payload untuk Alat Admin

Saat formulir dashboard dibangun, kumpulkan setidaknya:

• Platform — ios / android / kedua-duanya
• Mode — debug (QA) atau release (toko)
• Referensi Git — cabang atau label untuk membangun
• Pengguna — alamat email atau id pengguna untuk log audit (lewatkan) client_payload)

Pilihan: setelah menjalankan, biarkan CI mengirim balik ke admin API dengan URL unduh dari --output-record / build last-output.

Keamanan

• Autentikasi setiap webhook (x-webhook-secret, tanda tangan HMAC, atau mTLS).
• Daftar Izin platform, mode, dan ref di kedua proxy dan alur kerja — tatalah validate job — tindakan client_payload masuk sebagai input tidak terpercaya.
• Tunjukkan nilai yang diterima melalui variabel lingkungan / hasil pekerjaan; jangan mengganti bidang payload ke dalam run: scripts.
• Tetapkan GitHub/Token GitLab di server saja.
• Prefer tokens scoped to a single repository.
• Batasi proxy; pembangunan asli menghabiskan menit pembangunan.
• Untuk rilis yang dikirim ke toko, atur release ke sebuah lingkungan GitHub yang dilindungi (seperti contoh) atau memerlukan sebuah flag konfirmasi tambahan yang dicentang validate.

Bab berjudul “Panduan Terkait”

Sama __CAPGO_KEEP_0__ Tugas Bangun, dimulai dari tab Pipelines / Aksi. Proyek Capgo yang sama, dimulai dari tab Aksi / Pipa.

GitHub Actions setup Kredensial ekspor dan nama rahasia yang digunakan oleh alur kerja ini.

Auto OTA atau Native Pada push git, pilih secara otomatis antara live update dan asli.