Native Builds über Webhook auslösen

Capgo Die normale Build-Ausführung erfolgt normalerweise von einem Laptop oder CI-Auftrag. Teams, die von einem Verwaltungsdashboard, CMS oder internen Portal aus liefern, möchten oft eine einzelne HTTP-Webhook: 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 Organisation Webhooks (Dashboard → Organisation → Webhooks) benachrichtigen Ihre URLs über Capgo Ereignisse (Bündel, Kanäle, Mitglieder). Diese Seite ist die andere Richtung: Ihre Der Systemaufruf ruft eine URL auf, um eine eine 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

Sie machen Sie need Capgo to expose a public “build webhook.” Your CI already has the signing secrets; the webhook’s only job is to start that CI job safely.

Voraussetzungen

• Ein Capgo Build-Workflow, der bereits aus der CI-Oberfläche oder bei einem Push (GitHub Aktionen)
• Zugriff auf eine fein abgestufte GitHub-Token, GitLab-Auslöser-Token oder ein äquivalentes
• Ein gemeinsamer geheimer Schlüssel, den Ihr Admin-Dashboard sendet (Header oder Körper)

Option A — GitHub repository_dispatch (empfohlen)

GitHub akzeptiert einen authentifizierten API-Aufruf, der einen Workflow startet, der auf repository_dispatchJeder Dashboard, das kann POST JSON kann es auslösen.

1. Workflow, der auf das Webhook lauscht

Überprüfe die Payload vorher Überprüfen Sie und vor jeder geheimnisbaren Schritt. Passen Sie akzeptierte Werte durch Job-Ausgaben / Umgebungsvariablen – nie interpolieren. client_payload direkt ein run: direkt inSkriptinjektionsleitfaden).

/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 fein aufgeschichteten persönlichen Zugriffstoken (oder GitHub App-Installationstoken) mit Inhalt: Lesen und Schreiben auf dem Repository (erforderlich für repository_dispatchSpeichere es nur in Ihrem Admin-Backend – nie im Browser.

3. Ruf den Webhook von Ihrem Admin-Dashboard aus

Ihr Backend (nicht der Endbenutzer-Browser) 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	Stimmt types im Workflow (capgo-native-build)
client_payload.platform	ios, androidoder both
client_payload.mode	debug oder release
client_payload.ref	Zweig oder Tag zum Bauen (optional)

Verwenden Sie die gleiche JSON-POST-Anforderung für einen Button in Ihrer Admin-Oberfläche ("NATIVE-Apps erstellen"). Die Oberfläche muss nur bis zum your Hintergrund; der Hintergrund hält GITHUB_TOKEN.

Caution

Nie fügen Sie den GitHub Token in der Frontend-JavaScript-Code ein. Die Admin-Seite sollte Ihre Server aufrufen; Ihr Server ruft GitHub auf.

Option B — Tiny proxy webhook (jeder Host)

Wenn das Admin-Tool nur POST an eine von Ihnen kontrollierte URL senden kann (Zapier, Make, Cloudflare Worker, Express-Route), legen Sie 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,
    })
  },
}

Dann konfigurieren Sie das Admin-Produkt:

Einstellung	Wert
URL	https://your-worker.example.com/native-build
Methode	POST
Header	x-webhook-secret: <shared secret>
Körper	{ "platform": "both", "mode": "release" }

Dies ist die übliche Form, um einen Webhook an ein On-Admin-Dashboard anzuschließen: Das Dashboard speichert eine URL und einen geheimen Schlüssel; Capgo Anmeldeinformationen bleiben in GitHub Aktionen.

GitLab-Pipeline-Auslöser

GitLab legt Pipeline-Auslöser-Token die natürlichen Webhook-Ziele dar.

# .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 Auslöser-Token unter Einstellungen → CI/CD → Pipeline-Auslöser-Token, dann aus der Admin-Oberfläche:

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 löst man entweder zwei Auslöser aus oder erweitert das Job in ein paralleles Matrix-Format auf die gleiche Weise wie im Beispiel GitHub.

Bitbucket und Azure

Plattform	Webhook-Mechanismus
Bitbucket	Pipeline-Auslöser-URL oder benutzerdefinierte Pipeline + App-Passwort POST
Azure DevOps	Pipeline-Ausführung-REST API mit einem PAT; verwenden Sie die manuelle Pipeline von Auslöser aus der CI-Oberfläche

Muster ist identisch: Admin → Ihr geheimes Prüfen → Host API → Capgo Build-Job.

Payload-Übersicht für Admin-Tools

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

• Plattform — ios / android / beide
• Modus — Debug (QA) oder Release (Laden)
• Git-Referenz — Zweig oder Tag zum Bauen
• Akteur — E-Mail-Adresse oder Benutzer-ID für Audit-Protokolle (durchgeben) client_payload)

Optional: Nach dem Lauf soll die CI zurück an den Admin API mit der Download-URL senden --output-record / build last-output.

Sicherheit

• Authentifizieren Sie jeden Webhook (x-webhook-secretHMAC-Signatur oder mTLS).
• Zulassungsliste platform, mode, und ref in beiden dem Proxy und der Workflow validate Job — bearbeiten client_payload als unvertrauenswürdige Eingaben.
• Leiten Sie akzeptierte Werte über Umgebungsvariablen / Auftragsausgaben weiter; interpolieren Sie keine Payload-Felder in run: Skripte.
• Halten Sie GitHub/GitLab-Tokens ausschließlich serverseitig.
• Prefer tokens scoped to a single repository.
• Beschränken Sie den Proxy; native Builds kosten Build-Minuten.
• Für das Hinzufügen von Releases in den Store mappen release auf einen geschützten GitHub Umgebung (wie im Beispiel) oder fordern Sie eine zusätzliche Bestätigungsflag an. validate.

Zugehörige Anleitungen

Auslösen von CI UI Das gleiche Capgo Build-Job, gestartet von der Actions / Pipelines-Tabelle.

GitHub Actions-Einstellungen Kredenzialexport und geheime Namen, die von diesen Workflows verwendet werden.

Auto OTA oder Native Bei git push wählen Sie live update oder native automatisch.