Aktifkan Pembangunan Asli melalui Webhook

Capgo Pembangunan biasanya dimulai dari laptop atau pekerjaan CI. Tim yang mengirim dari dashboard admin Siap untuk dipasangatau portal internal sering ingin memiliki satu webhook HTTP: tekan tombol di antarmuka mereka sendiri, dan sebuah build native yang ditandatangani dimulai. Panduan ini menunjukkan pola standar — panggilan HTTP yang terautentik dan tipis ke host code Anda, yang menjalankan alur kerja Build Capgo yang sama yang Anda gunakan sebelumnya.

Catatan

Capgo webhooks organisasi (Dashboard → Organisasi → Webhooks) mengirimkan URL Anda tentang __CAPGO_KEEP_0__ acara (bundel, saluran, anggota). Halaman ini adalah arah lain: URLs about Capgo events (bundles, channels, members). This page is the other direction: untuk memulai __CAPGO_KEEP_0__ Build. a 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 melakukan tidak perlu Capgo untuk mengungkapkan webhook “build” yang publik. CI Anda sudah memiliki rahasia tanda tangan; pekerjaan webhook hanyalah untuk memulai pekerjaan CI tersebut dengan aman.

Prasyarat

• Alur kerja Capgo Build yang sudah berfungsi dari Antarmuka Pengguna CI atau pada push (GitHub Actions)
• Izin untuk membuat token yang halus GitHub , token trigger GitLab, atau setara
• Rahasia yang dibagikan yang akan dikirim oleh dashboard admin (header atau body)

Pilihan A — GitHub repository_dispatch (direkomendasikan)

GitHub menerima panggilan API yang terotentikasi yang memulai alur kerja yang mendengarkan untuk repository_dispatch. Apapun dashboard yang dapat POST JSON dapat mengirimkannya.

1. Alur kerja yang mendengarkan webhook

Validasi isi payload sebelumnya checkout dan sebelum langkah apa pun yang mengandung rahasia. Kirimkan nilai-nilai yang diterima melalui keluaran pekerjaan / variabel lingkungan — tidak pernah menggantikan client_payload langsung ke run: skrip (petunjuk injeksi skrip).

github/kerja/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 token GitHub

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

3. Panggil webhook dari dashboard admin Anda

Server 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 sesuai types dalam alur kerja (capgo-native-build)
client_payload.platform	ios, android, atau both
client_payload.mode	debug atau release
client_payload.ref	atau nama cabang (opsional)

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

Pertimbangan

Hati-hati jangan menyematkan GitHub token ke JavaScript frontend. Halaman admin harus memanggil server Anda; server Anda memanggil GitHub.

Option B — Webhook proxy kecil (host apa saja)

Jika alat admin hanya dapat mengirimkan POST ke URL yang Anda kendalikan (Zapier, Make, Cloudflare Worker, jalur Express), letakkan proxy singkat 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 atur produk admin:

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

Biasanya bentuk ini digunakan untuk menghubungkan sebuah webhook ke dashboard admin: dashboard menyimpan satu URL dan satu rahasia; Capgo kredential tetap di GitHub Aksi.

Pemicu Aliran GitLab

GitLab mengungkapkan token pemicu aliran yang merupakan target webhook 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"'

Membuat token trigger di bawah Pengaturan → CI/CD → Token trigger pipeline, 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, baiklah melepaskan dua trigger atau memperluas pekerjaan menjadi matriks parallel yang sama seperti contoh GitHub.

Bitbucket dan Azure

Platform	Mekanisme webhook
Bitbucket	URL trigger pipeline atau pipeline kustom + kata sandi aplikasi POST
Azure DevOps	Pipeline run REST API dengan PAT; gunakan pipeline manual dari Trigger dari UI CI

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

Daftar Periksa Payload untuk Alat Admin

Ketika formulir dashboard dibangun, koleksi setidaknya:

• Platform — ios / android / kedua
• Mode — debug (QA) atau rilis (toko)
• Referensi Git — cabang atau tag untuk dibangun
• Pemain — alamat email atau ID pengguna untuk log audit (melewati) client_payload)

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

Keamanan

• Bab berjudul 'Keamanan'x-webhook-secretAutentikasi setiap webhook (
• tanda tangan HMAC, atau mTLS). platform, modeDaftar Izin (Allowlist) ref di kedua proxy dan alur kerja validate pekerjaan — terlakukan client_payload sebagai input tidak terpercaya.
• Kirimkan nilai yang diterima melalui env var / keluaran pekerjaan; jangan menginterpolasi bidang payload ke run: skrip.
• Tahan GitHub/Token GitLab di sisi server saja.
• Lebih baik menggunakan token yang terbatas pada repositori tunggal.
• Batasi kecepatan proxy; pembangunan asli menghabiskan menit pembangunan.
• context: Halaman/area: Pembangun Capgo / halaman produk produk pembangunan asli di awan. Peran: Kalimat website. Dilihat di: halaman native-build.astro. Pesan kunci `native_build_builder_build_minutes` (Menit Pembangunan Pembangun Pembangunan Asli). release to a protected GitHub Environment (as in the sample) or require an extra confirmation flag checked in validate.

ke lingkungan __CAPGO_KEEP_0__ yang dilindungi (seperti contoh) atau memerlukan flag konfirmasi tambahan yang diperiksa di

Trigger dari CI UI Proyek Capgo yang sama, dimulai dari tab Aksi / Pipa.

GitHub Pengaturan Aksi Nama rahasia dan nama kunci yang digunakan oleh alur kerja ini.

Auto OTA atau Native Pilih pembaruan otomatis vs native secara otomatis setelah push ke Git.