Native Builds via Webhook triggern

Capgo Build wird normalerweise von einem Laptop oder einem CI-Job gestartet. Teams, die aus einem Admin-Dashboard, CMS oder interne Portale möchten oft ein einzelnes HTTP-Webhook: Ein Klick in ihrer eigenen UI genügt, um einen signierten Native Build zu starten. Dieser Guide zeigt das Standard-Pattern – einen einfachen, authentifizierten HTTP-Call an deinen code Host, der denselben Capgo Build-Workflow ausführt, den du bereits nutzt.

Hinweis

Capgo Organisations-Webhooks (Dashboard → Organisation → Webhooks) benachrichtigen deine URLs über Capgo Events (Bundles, Channels, Mitglieder). Diese Seite beschreibt die umgekehrte Richtung: deine das System ruft eine URL auf, um starten einen Capgo Build zu starten.

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. Deine CI besitzt bereits die Signing-Secrets; die einzige Aufgabe des Webhooks ist es, diesen CI-Job sicher zu starten.

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)

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

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

.github/workflows/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. Erstelle einen GitHub Token

Erstelle einen feingranularen Personal Access Token (oder einen GitHub App-Installations-Token) mit Inhalt: Read und Write im Repository (erforderlich für repository_dispatch). Speichere ihn nur in deinem Admin-Backend — niemals im Browser.

3. Webhook über dein Admin-Dashboard aufrufen

Dein Backend (nicht der Browser des Endnutzers) sollte Folgendes 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 zum Build (optional)

Verknüpfe denselben JSON POST mit einem Button in deinem Admin-UI („Build native apps“). Das Dashboard muss lediglich Zugriff haben auf dein Backend; das Backend hält GITHUB_TOKEN.

Achtung

Bette den GitHub Token niemals in Frontend-JavaScript ein. Die Admin-Seite sollte deinen Server aufrufen; dein Server ruft GitHub auf.

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

GitLab stellt Pipeline-Trigger-Tokens bereit, die sich ideal als Webhook-Ziele eignen.

# .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"'

Erstelle ein Trigger-Token unter Einstellungen → CI/CD → Pipeline-Trigger-Tokens, und dann im 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/pipeline

Für beide Plattformen kannst du entweder zwei Trigger auslösen oder den Job in eine parallele Matrix aufteilen, genau wie im GitHub Beispiel.

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

Wenn das Dashboard-Formular erstellt wird, sammeln Sie mindestens:

• Plattform — ios / android / beide
• Modus — debug (QA) oder release (Store)
• Git-Ref — Branch oder Tag für den Build
• Actor — E-Mail oder User-ID für Audit-Logs (durchreichen) client_payload)

Optional: Nach dem Run kann die CI die Download-URL an den Admin API zurückmelden --output-record / build last-output.

Sicherheit

• Authentifizierung für jeden Webhook (x-webhook-secret, HMAC-Signatur oder mTLS).
• Allowlist platform, mode, und ref sowohl im Proxy als auch im Workflow- validate Job – behandle client_payload als unvertrauenswürdige Eingabe.
• Reiche akzeptierte Werte über Env-Vars / Job-Outputs weiter; interpoliere keine Payload-Felder in run: Skripte.
• Halte GitHub/GitLab-Token ausschließlich serverseitig.
• Prefer tokens scoped to a single repository.
• Rate-Limit für den Proxy nutzen; Native Builds verbrauchen Build-Minuten.
• For store-submitting releases, map release auf eine geschützte GitHub Umgebung (wie im Beispiel) oder fordern Sie ein zusätzliches Bestätigungs-Flag an, das in validate.

Verwandte Guides

Trigger aus CI-UI demselben Capgo Build-Job geprüft wird, der über den Actions / Pipelines Tab gestartet wurde.

GitHub Actions Setup Credential-Export und Secret-Namen, die in diesen Workflows verwendet werden.

Auto OTA oder Native Wählen Sie bei einem git push automatisch live update vs. Native.