Trigger native Builds über Webhook

Capgo Die Build-Erstellung erfolgt normalerweise von einem Laptop oder CI-Job aus. Teams, die von einem Verwaltungsoberfläche aus liefern, CMS oder interne Portal möchten oft ein einziges HTTP-Webhook: Klicken Sie auf einen Button in Ihrer eigenen Benutzeroberfläche und ein signierter native Build wird gestartet. Dieses Handbuch zeigt das Standardmuster – eine dünne, authentifizierte HTTP-Anfrage in Ihren code-Host, der den gleichen Capgo-Build-Workflow ausführt, den Sie bereits verwenden.

Anmerkung

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

Sie müssen nicht Capgo

Zu den Voraussetzungen

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

Option A — GitHub repository_dispatch (empfohlen)

GitHub akzeptiert einen authentifizierten API-Aufruf, der einen Workflow startet, der auf GitHub lauscht, die für repository_dispatch. Jeder Dashboard, der POST JSON kann es auslösen.

1. Workflow, der auf den Webhook lauscht

Die Nachricht überprüfen vorher, im Kontext: HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `create_an_issue_and_discuss_before_working_on_a_new_feature`). Seite/Bereich: Capgo-Marketingwebsite. Rolle: Langen Marketing- oder Rechtsparagraphen. Gesehen in: Seite contributing.astro. Nachrichtenschlüssel `create_an_issue_and_discuss_before_working_on_a_new_feature` (Create An Issue And Discuss Before Working On A New Feature). | HTML-Textfragment aus einem längeren Capgo-UI-String (Elternschlüssel `mention_issue_before_working`). Seite/Bereich: Capgo-Marketingwebsite. Rolle: Website-Kopfsatz. Gesehen in: Seite contributing.astro. Nachrichtenschlüssel `mention_issue_before_working` (Mention Issue Before Working). checkout und vor jeder geheimnisvollen Schritt. Akzeptierte Werte übermitteln Sie über Job-Ausgaben / Umgebungsvariablen — nie interpolieren client_payload direkt in run: Skripte (Anleitung zum Skriptinjection).

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. Erstellen Sie einen GitHub-Token

Erstellen Sie einen fein abgestuften 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	in der Workflow- (oder

Wire the same JSON POST an einen Button in Ihrer Verwaltungsoberfläche (‘Native-Apps erstellen’). Die Oberfläche muss nur mit Ihrem Backend kommunizieren; das Backend hält Dein Backend hält 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 Verwaltungsoberfläche 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,
    })
  },
}

Zwischenablage kopieren

Dann konfigurieren Sie das Verwaltungstool:	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 eine Webhook-Verbindung zu einem Admin-Dashboard anzuschließen: Das Dashboard speichert eine URL und einen geheimen Schlüssel; Capgo-Anmeldedaten bleiben in GitHub Aktionen.

GitLab Pipeline Trigger

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

# .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 Administrator-Hintergrundanwendung:

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 einen parallelen Matrix aufteilen, wie im Beispiel GitHub.

Bitbucket und Azure

Plattform	Webhook-Mechanismus
Bitbucket	Pipeline-Trigger-URL oder benutzerdefinierte Pipeline + App-Passwort POST
Azure DevOps	Pipeline-Run-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.

Zustandsübersicht für Admin-Tools

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

• Plattform — ios / android / beide
• Modus — Debug (QA) oder Release (Händler)
• 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

• Authentifizieren Sie jeden Webhook (x-webhook-secretZulassungsliste
• und platform, modeZulassungsliste ref im Proxy und im Workflow validate Job — behandeln client_payload als nicht vertrauenswürdigen Eingaben.
• Übergebene Werte durch Umgebungsvariablen / Job-Ausgaben weitergeben; 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 in validate.

Führen Sie

Auslöser aus CI UI Same Capgo Build job, started from the Actions / Pipelines tab.

Aufbau von GitHub Zugriffskennwortexport und geheime Namen dieser Workflows.

Auto OTA oder Native Bei git push, wählen Sie zwischen live-Update und Native automatisch.