Zum Inhalt springen

Native Builds via Webhook triggern

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.

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.

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

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.

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"

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.

Ihr Backend (nicht der Browser des Endnutzers) sollte senden:

Terminalfenster
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"
}
}'
FeldZweck
event_typeMust match types im Workflow (capgo-native-build)
client_payload.platformios, android, oder both
client_payload.modedebug oder release
client_payload.refBranch 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.

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:

EinstellungWert
URLhttps://your-worker.example.com/native-build
MethodePOST
Headerx-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 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"'

Erstellen Sie ein Trigger-Token unter Einstellungen → CI/CD → Pipeline-Trigger-Tokens, dann aus dem Admin-Backend:

Terminalfenster
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 entweder zwei Triggers auslösen oder den Job wie im GitHub-Beispiel in eine parallele Matrix aufteilen.

PlattformWebhook-Mechanismus
BitbucketPipeline-Trigger-URL oder Custom Pipeline + App-Passwort POST
Azure DevOpsPipeline-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.

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.

  • Jeden Webhook authentifizieren (x-webhook-secret, HMAC-Signatur oder mTLS).
  • Allowlist platform, mode, und ref sowohl im Proxy als auch im Workflow validate Job — behandeln Sie client_payload als 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 release auf eine geschützte GitHub-Umgebung (wie im Beispiel) oder verlangst ein zusätzliches Bestätigungsflag, das in validate.