Trigger native Builds über Webhook

Capgo Die Build-Start-Phase wird normalerweise von einem Laptop oder CI-Job ausgelöst. Teams, die von einem Verwaltungsoberfläche aus liefernWebhooks für die __CAPGO_KEEP_0__-Hosts HTTP-Webhook: Klicken Sie auf einen Button in Ihrer eigenen Benutzeroberfläche und ein signiertes natives Build beginnt. Diese Anleitung zeigt das Standardmuster – einen dünnen authentifizierten HTTP-Aufruf in Ihren code-Host, der das gleiche Capgo-Build-Workflow ausführt, den Sie bereits verwenden.

Hinweis

Capgo-Organisations-Webhooks (Dashboard → Organisation → Webhooks) melden ihre URLs über Capgo-Ereignisse (Bundles, Kanäle, Mitglieder). Diese Seite ist die andere Richtung: ihre System ruft eine URL auf, um ein __CAPGO_KEEP_0__-Build zu starten. starten a Capgo Build.

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 müssen nicht Capgo

Voraussetzungen

• Ein Capgo Build-Workflow, der bereits aus der CI-Oberfläche oder bei Push (GitHub Actions)
• Erlaubnis, um eine fein abgestufte GitHub-Token, ein GitLab-Auslöser-Token oder ein äquivalentes zu erstellen
• Eine gemeinsame Geheimzahl, die Ihr Administrator-Bereich sendet (Kopfzeile oder Körper)

Option A — GitHub repository_dispatch (empfohlen)

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

1. Workflow, der auf den Webhook wartet

Validieren Sie die Payload vorher (im Kontext von Capgo UI, siehe create_an_issue_and_discuss_before_working_on_a_new_feature und mention_issue_before_working) überprüfen und vor jeder geheimnisbaren Schritt. Akzeptierte Werte übergeben Sie durch Job-Ausgaben / Umgebungsvariablen — nie interpolieren client_payload direkt in run: Skripte (Anleitung zur Skriptinjektion).

github/Arbeitsabläufe/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. Erstellen Sie einen GitHub-Token

Erstellen Sie einen fein abgestimmten persönlichen Zugriffstoken (oder GitHub-App-Installationstoken) mit Inhalt: Lesen und schreiben auf dem Repository (erforderlich für repository_dispatchSpeichern Sie es nur in Ihrem Admin-Hintergrund — nie im Browser.

3. Rufen Sie die Webhook-Funktion aus Ihrem Admin-Bereich auf

Ihre Backend-Instanz (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	Sollte übereinstimmen types in der Workflow- (capgo-native-build)
client_payload.platform	ios, androidoder both
client_payload.mode	debug oder release
client_payload.ref	oder

Wire die gleiche JSON-POST-Anfrage an einen Schaltknopf in Ihrer Admin-Oberfläche (‘Native-Apps erstellen’). Die Oberfläche muss nur mit Ihrem Backend kommunizieren; das Backend hält deine Backend GITHUB_TOKEN.

Vorsicht

Never embed the GitHub token in frontend JavaScript. The admin page should call your server; your server calls GitHub.

Nie den __CAPGO_KEEP_0__-Token in Frontend-JavaScript einbetten. Die Admin-Seite sollte Ihren Server aufrufen; Ihr Server ruft __CAPGO_KEEP_1__ auf.

If the admin tool can only POST to a URL you control (Zapier, Make, Cloudflare Worker, Express route), put a short proxy in front of 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,
    })
  },
}

Zur Vervollständigung in die Zwischenablage kopieren

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

Diese ist die übliche Form, um einen Webhook an einem On-Admin-Dashboard anzuschließen: Das Dashboard speichert eine URL und ein Geheimnis; Capgo-Anmeldedaten bleiben in GitHub Aktionen.

GitLab Pipeline Trigger

GitLab legt Pipeline-Auslöse-Token aus, die natürliche Webhook-Ziele sind.

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

Ein Trigger-Token unter Einstellungen → CI/CD → Pipeline-Trigger-Token, dann aus der 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 können Sie entweder zwei Trigger auslösen oder das Job in ein paralleles Matrix wie im Beispiel GitHub erweitern.

Bitbucket und Azure

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

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

Zusammenfassung des Payloads für Admin-Tools

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

• Plattform — ios / android / beide
• Modus — Entwicklungs- (QA) oder Veröffentlichungs- (Store)
• Git-Referenz — Zweig oder Versionsnummer zum Bauen
• Akteur — E-Mail-Adresse oder Benutzer-ID für Audit-Protokolle (durchgehen) client_payload)

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

Sicherheit

• Jeder Webhook authentifizieren (x-webhook-secretZulassungsliste
• und platform, modeAllowlist ref im Proxy und im Workflow validate Job — behandeln client_payload als unvertrauenswürdigen Eingaben.
• Passierte Werte über Umgebungsvariablen / Job-Ausgaben weiter; interagiere nicht mit Payload-Feldern in run: Skripte.
• Halten Sie GitHub/GitLab-Tokens ausschließlich serverseitig auf.
• Präferieren Sie Tokens, die auf ein einzelnes Repository beschränkt sind.
• Beschränken Sie den Proxy; native Builds kosten Build-Minuten.
• Für store-submitting Releases, mappen Sie release zu einem geschützten GitHub Umgebungsvariablen (wie im Beispiel) oder fordern Sie eine zusätzliche Bestätigungsflag an, die auf validate.

Führen Sie sich zu den folgenden Anleitungen um

Auslöser aus CI-Benutzeroberfläche Same Capgo Build job, started from the Actions / Pipelines tab.

GitHub Aktionen einrichten Zugriffsdatenexport und geheime Namen, die diese Workflows verwenden.

Auto OTA oder Native Bei Git-Push: Wahl zwischen Live-Update und Native automatisch.