Attivare costruzioni native tramite webhook

Capgo Il build è normalmente avviato da un laptop o un lavoro di CI. Le squadre che inviano da un pannello di controllo amministrativo, CMS o portale interni desiderano spesso un singolo webhook HTTP: clicca un pulsante nella propria interfaccia utente e inizia una compilazione nativa firmata. Questa guida mostra il modello standard — un chiamata HTTP autenticata sottile nella tua host code, che esegue lo stesso workflow di compilazione Capgo che già utilizzi.

Nota

Capgo le webhook dell'organizzazione (Dashboard → Organizzazione → Webhook) notificano il tuo URLs sulle Capgo eventi (bundle, canali, membri). Questa pagina è l'altro senso: il tuo sistema chiama un URL per avviare una Capgo compilazione.

Architettura

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

Fai non hanno bisogno di Capgo per esporre un webhook di “build” pubblico. Il tuo CI già possiede i segreti di firma; l'unico compito dell'hook è avviare quel job CI in modo sicuro.

Requisiti

• Un flusso di lavoro Capgo Build che già funziona dalla interfaccia utente del CI o al push (GitHub Actions)
• La possibilità di creare un token fine-grained GitHub, un token di trigger GitLab o equivalente
• Un segreto condiviso che il tuo dashboard amministrativo invierà (intestazione o corpo)

Opzione A — GitHub repository_dispatch Consigliato

GitHub accetta un chiamata autenticata API che avvia un flusso di lavoro che ascolta per repository_dispatch. Qualsiasi dashboard che può POST JSON può attivarlo.

1. Flusso di lavoro che ascolta il webhook

Valida il payload prima di tutto, nel contesto di un testo HTML da una stringa di Capgo UI più lunga (chiave genitrice `create_an_issue_and_discuss_before_working_on_a_new_feature`). Pagina/Area: Sito web di marketing di Capgo. Ruolo: Paragrafo di marketing o legale lungo. Visto in: pagina contributing.astro. Chiave messaggio `create_an_issue_and_discuss_before_working_on_a_new_feature` (Crea un Issue e Discuti Prima di Lavorare su una Nuova Funzionalità). | Testo frammento HTML da una stringa di Capgo UI più lunga (chiave genitrice `mention_issue_before_working`). Pagina/Area: Sito web di marketing di Capgo. Ruolo: Frase di copertina del sito web. Visto in: pagina contributing.astro. Chiave messaggio `mention_issue_before_working` (Menziona l'Issue Prima di Lavorare). verifica e prima di qualsiasi passaggio che comporta segreti. Passa i valori accettati attraverso gli output del job / le variabili di ambiente — mai interpolare client_payload direttamente in run: scripts (linee guida per l'iniezione di script).

github/lavorazioni/capgo-costruzione-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. Crea un token GitHub

Crea un token di accesso personalizzato fine-granulare (o un token di installazione dell'app GitHub) con Contenuto: Leggi e scrivi nel repository (richiesto per repository_dispatch) Conservalo solo nel tuo backend di amministrazione — mai nel browser.

3. Chiamare il webhook dal tuo pannello di amministrazione

La tua backend (non il browser dell'utente finale) dovrebbe inviare:

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"
    }
  }'

Campo	Scopo
event_type	Deve corrispondere types nel flusso di lavoro (capgo-native-build)
client_payload.platform	ios, androido both
client_payload.mode	debug o release
client_payload.ref	o

Collega lo stesso JSON POST a un pulsante nella tua interfaccia amministrativa ('Costruisci app native'). La dashboard deve raggiungere solo il tuo backend; il backend detiene GITHUB_TOKEN.

Attenzione

Non inserire mai il GitHub token nel JavaScript frontend. La pagina amministrativa dovrebbe chiamare il tuo server; il tuo server chiama GitHub.

Opzione B — Webhook proxy piccolo (qualsiasi host)

Se lo strumento amministrativo può solo inviare POST a un URL che controlli (Zapier, Make, Cloudflare Worker, route Express), metti un breve proxy davanti a 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,
    })
  },
}

Poi configura il prodotto amministrativo:

Impostazione	Valore
URL	https://your-worker.example.com/native-build
Metodo	POST
Intestazione	x-webhook-secret: <shared secret>
Corpo	{ "platform": "both", "mode": "release" }

Di solito, la forma per connettere un webhook a un dashboard di amministrazione è la seguente: il dashboard memorizza una URL e un segreto; i Capgo credenziali rimangono in GitHub azioni.

Trigger di flusso GitLab

GitLab espone token di trigger di flusso che sono naturali target webhook.

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

Creare un token di attivazione sotto Impostazioni → CI/CD → Token di attivazione della pipeline, quindi dal backend amministrativo:

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

Per entrambe le piattaforme, si possono attivare due trigger o espandere il lavoro in una matrice parallela nello stesso modo dell'esempio GitHub.

Bitbucket e Azure

Piattaforma	Meccanismo di webhook
Bitbucket	URL di attivazione della pipeline o pipeline personalizzato + password dell'applicazione POST
Azure DevOps	Esecuzione del pipeline REST API con un token di accesso; utilizzare il pipeline manuale da Attivazione da interfaccia utente di CI

Il modello è identico: amministratore → verifica del segreto → host API → Capgo Job di costruzione.

Elenco dei controlli per il payload degli strumenti di amministrazione

Quando la forma del dashboard è creata, raccogliere almeno:

• Piattaforma — ios / android / entrambi
• Modalità – debug (QA) o rilascio (store)
• Riferimento Git – ramo o etichetta per la costruzione
• Attore – indirizzo email o ID utente per i registri di audit (pass through) client_payload)

Facoltativo: dopo l'esecuzione, far riferire il CI all'amministratore API con l'URL di download da --output-record / build last-output.

Sicurezza

• Autenticare ogni webhook (x-webhook-secretElenco consentiti
• , e platform, mode– firma HMAC o mTLS ref In entrambi il proxy e il workflow validate — trattalo client_payload come input non affidabile.
• Passa i valori accettati attraverso le variabili di ambiente / gli output del lavoro; non interpolare i campi del payload nei run: script.
• Conserva i token GitHub/GitLab solo sul server.
• Preferisci i token limitati a un singolo repository.
• Limita il proxy; le costruzioni native costano minuti di costruzione.
• Per le rilasci che inviano allo store, mappa release a un ambiente protetto GitHub (come nell'esempio) o richiedi un flag di conferma aggiuntivo controllato in validate.

Guida correlata

Attiva da CI UI Lo stesso Capgo job di costruzione, avviato dalla scheda Azioni / Pipeline.

GitHub Impostazioni azioni Esportazione delle credenziali e i nomi dei segreti utilizzati da questi flussi di lavoro.

Auto OTA o Nativo Al push su Git, scegli l'aggiornamento in tempo reale o nativo automaticamente.