Native Builds via Webhook triggern
Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.
Capgo Build wird normalerweise von einem Laptop oder CI-Job gestartet. Teams, die aus einem Admin-Dashboard, CMS oder internes Portal möchten häufig ein einzelnes HTTP-Webhooknutzen: Einen Button in ihrer eigenen UI drücken, und ein signierter Native Build startet. Dieser Guide zeigt das Standardmuster – ein dünner, authentifizierter HTTP-Call an deinen code-Host, der denselben Capgo Build-Workflow ausführt, den du bereits nutzt.
Architektur
Abschnitt mit dem Titel „Architektur“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
Du benötigst es nicht benötigen Capgo, um einen öffentlichen „Build-Webhook“ bereitzustellen. Ihre CI verfügt bereits über die Signierungsgeheimnisse; die einzige Aufgabe des Webhooks besteht darin, diesen CI-Job sicher zu starten.
Voraussetzungen
Abschnitt: „Voraussetzungen“- Ein Capgo Build-Workflow, der bereits über die CI-UI oder per Push funktioniert (GitHub Aktionen)
- Berechtigung zum Erstellen eines feingranularen GitHub Tokens, eines GitLab-Trigger-Tokens oder etwas Vergleichbarem
- Ein Shared Secret, das dein Admin-Dashboard sendet (Header oder Body)
Option A — GitHub repository_dispatch (empfohlen)
Abschnitt mit dem Titel „Option A — GitHub repository_dispatch (empfohlen)“GitHub akzeptiert einen authentifizierten API-Call, der einen Workflow startet, der auf repository_dispatch. Jedes Dashboard, das POST JSON senden kann, kann es auslösen.
1. Workflow, der auf den Webhook wartet
Abschnitt mit dem Titel „1. Workflow, der auf den Webhook wartet“Payload validieren bevor beim Checkout und vor jedem Schritt mit Secrets. Übergib akzeptierte Werte über Job-Outputs / Env-Vars — niemals client_payload directly into run: Skripte (Hinweise zur 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. GitHub-Token erstellen
Abschnitt mit der Überschrift „2. GitHub-Token erstellen“Erstellen Sie ein feingranulares persönliches Zugriffstoken (oder ein GitHub-App-Installationstoken) mit Contents: Lesen und Schreiben im Repository (erforderlich für repository_dispatch). Speichern Sie es ausschließlich in Ihrem Admin-Backend – niemals im Browser.
3. Webhook aus dem Admin-Dashboard aufrufen
Abschnitt mit der Überschrift „3. Webhook aus Ihrem Admin-Dashboard aufrufen“Ihr Backend (nicht der Browser des Endnutzers) sollte senden:
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" } }'| Feld | Zweck |
|---|---|
event_type | Must match types im Workflow (capgo-native-build) |
client_payload.platform | ios, android, oder both |
client_payload.mode | debug oder release |
client_payload.ref | Branch oder Tag für den Build (optional) |
Verdrahten Sie denselben JSON-POST an einen Button in Ihrer Admin-UI („Native Apps bauen“). Das Dashboard muss nur erreichbar sein deine Backend erreichen; das Backend hält GITHUB_TOKEN.
Option B — Kleiner Proxy-Webhook (beliebiger Host)
Abschnitt mit dem Titel „Option B — Kleiner Proxy-Webhook (beliebiger Host)“Wenn das Admin-Tool nur POST-Requests an eine URL senden kann, die du kontrollierst (Zapier, Make, Cloudflare Worker, Express-Route), schalte einen kurzen Proxy vor 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, }) },}Konfiguriere dann das Admin-Produkt:
| Einstellung | Wert |
|---|---|
| URL | https://your-worker.example.com/native-build |
| Methode | POST |
| Header | x-webhook-secret: <shared secret> |
| Body | { "platform": "both", "mode": "release" } |
Dies ist das übliche Format, um einen Webhook mit einem Admin-Dashboard zu verbinden: Das Dashboard speichert eine URL und ein Secret; die Capgo Credentials bleiben in GitHub Actions.
GitLab-Pipeline-Trigger
Abschnitt mit dem Titel „GitLab Pipeline Trigger“GitLab stellt Pipeline-Trigger-Tokens bereit, die sich ideal als Webhook-Ziele eignen.
# .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"'Erstellen Sie ein Trigger-Token unter Einstellungen → CI/CD → Pipeline-Trigger-Tokens, dann aus dem Admin-Backend:
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/pipelineFür beide Plattformen entweder zwei Triggers auslösen oder den Job wie im GitHub-Beispiel in eine parallele Matrix aufteilen.
Bitbucket und Azure
Abschnitt mit dem Titel „Bitbucket und Azure“| Plattform | Webhook-Mechanismus |
|---|---|
| Bitbucket | Pipeline-Trigger-URL oder Custom Pipeline + App-Passwort POST |
| Azure DevOps | Pipeline-Run REST API mit einem PAT; nutze die manuelle Pipeline von Trigger aus CI-UI |
Das Muster ist identisch: Admin → dein Secret-Check → Host API → Capgo Build-Job.
Payload-Checkliste für Admin-Tools
Abschnitt mit dem Titel „Payload-Checkliste für Admin-Tools“Wenn das Dashboard-Formular erstellt wird, mindestens erfassen:
- Plattform — ios / android / beide
- Modus — debug (QA) oder release (Store)
- Git-Ref — Branch oder Tag zum Builden
- Akteur — E-Mail oder Benutzer-ID für Audit-Logs (weiterleiten
client_payload)
Optional: Nach dem Run CI an das Admin-API mit der Download-URL von --output-record / build last-output.
Sicherheit
Abschnitt mit dem Titel „Sicherheit“- Jeden Webhook authentifizieren (
x-webhook-secret, HMAC-Signatur oder mTLS). - Allowlist
platform,mode, undrefsowohl im Proxy als auch im WorkflowvalidateJob — behandeln Sieclient_payloadals nicht vertrauenswürdige Eingabe. - Übergebe akzeptierte Werte über Env Vars / Job Outputs; interpoliere keine Payload-Felder in
run:Skripte. - Halte GitHub/GitLab-Tokens ausschließlich serverseitig.
- Verwende Tokens, die auf ein einzelnes Repository beschränkt sind.
- Rate-limite den Proxy; native Builds kosten Build-Minuten.
- For store-submitting releases, map
releaseauf eine geschützte GitHub-Umgebung (wie im Beispiel) oder verlangst ein zusätzliches Bestätigungsflag, das invalidate.