Aktifkan Pembangunan Asli melalui Webhook

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

Capgo Pembangunan biasanya dimulai dari laptop atau pekerjaan CI. Tim yang mengirim dari dashboard admin dashboard adminatau portal internal sering kali ingin memiliki satu webhook HTTP: tekan tombol di UI mereka sendiri, dan sebuah build native yang ditandatangani akan 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.

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 mengekspos sebuah webhook publik “build.” CI Anda sudah memiliki rahasia tanda tangan; webhook hanya bertugas untuk memulai pekerjaan CI tersebut dengan aman.

Prasyarat

Suatu Capgo Build workflow yang sudah berfungsi dari UI CI atau pada push (GitHub Aksi)
Izin untuk membuat token GitHub yang halus, token trigger GitLab, atau setara
Rahasia bersama yang dashboard admin Anda akan kirim (header atau body)

Pilihan A — GitHub `repository_dispatch` rekomendasi

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

1. Alur kerja yang mendengarkan webhook

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

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

1. Panggil webhook dari dashboard admin Anda

Server backend (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"
    }
  }'

Field	Tujuan
`event_type`	Mengharuskan `types` di dalam alur kerja (`capgo-native-build`)
`client_payload.platform`	`ios`, `android`atau `both`
`client_payload.mode`	`debug` atau `release`
`client_payload.ref`	atau cabang atau tag untuk dibangun (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.

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 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 atur produk admin:

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

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

Trigger Pipa GitLab

GitLab mengungkapkan token trigger pipa 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 melempar 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	REST pipeline run API dengan PAT; gunakan pipeline manual dari Trigger dari UI CI

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

Daftar Periksa Payload untuk Alat Admin

Saat formulir dashboard dibangun, koleksi setidaknya:

Platform — ios / android / kedua-duanya
Mode — debug (QA) atau rilis (toko)
Referensi Git — cabang atau tag untuk dibangun
Actor — 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

Autentikasi setiap webhook (x-webhook-secretDaftar Izin
, dan platform, modeHMAC signature, atau mTLS). ref di kedua proxy dan alur kerja validate pekerjaan — terlakukan client_payload sebagai input tidak dipercaya.
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 pembangunan awan asli. Peran: Kalimat situs web. 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.

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

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

Auto OTA atau Native Pada push git, pilih pembaruan hidup vs native secara otomatis.