Attivare costruzioni native tramite webhook

Copiare un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Capgo Il build è normalmente avviato da un laptop o un lavoro di CI. Le squadre che inviano da un'interfaccia amministrativa interfaccia amministrativa, CMS o portale interni spesso desiderano un singolo webhook HTTP: premere un pulsante nella propria interfaccia utente e avviare un build nativo firmato. Questa guida mostra il pattern standard — un chiamata HTTP autenticata sottile nella tua host code, che esegue lo stesso workflow di Build Capgo che già utilizzi.

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

Tu devi non avere bisogno di Capgo per esporre un webhook pubblico “di costruzione.” Il tuo CI già ha i segreti di firma; il compito del webhook è solo quello di avviare quel lavoro di CI in modo sicuro.

Prerequisiti

Un flusso di lavoro Capgo Build che già funziona dalla interfaccia utente di CI o all'invio (GitHub Actions)
La possibilità di creare un token GitHub fine-granulare, 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 una 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'area di contribuzione del sito web di marketing di Capgo, significa prima di iniziare a lavorare su una nuova funzionalità, e nel contesto di un'area di contribuzione del sito web di marketing di Capgo, significa prima di iniziare a lavorare su una nuova funzionalità verifica e prima di qualsiasi passaggio che richiede una chiave segreta. Passa i valori accettati attraverso gli output del job / le variabili di ambiente — mai interpolare client_payload direttamente in run: script (guida per l'iniezione di script).

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 sulla repository (richiesto per repository_dispatch). Allocca solo nel tuo backend amministrativo — mai nel browser.

3. Chiamare il webhook dal tuo pannello di controllo amministrativo

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` in il flusso di lavoro (`capgo-native-build`)
`client_payload.platform`	`ios`, `android`o `both`
`client_payload.mode`	`debug` o `release`
`client_payload.ref`	o

Collega lo stesso JSON POST a un pulsante nella tua interfaccia utente di amministrazione (“Crea applicazioni native”). La dashboard deve raggiungere solo il tuo backend; il backend detiene GITHUB_TOKEN.

Opzione B — Webhook proxy piccolo (qualsiasi host)

Se lo strumento di amministrazione può solo inviare una richiesta 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 di amministrazione:

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

Questa è la forma usuale per connettere un webhook a un dashboard di amministrazione: il dashboard memorizza una sola URL e un segreto; i Capgo credenziali rimangono in GitHub azioni.

Trigger di pipeline GitLab

GitLab espone token di trigger di pipeline che sono naturali bersagli 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 segreta → host API → Capgo Job di costruzione.

Elenco dei dati di payload per strumenti di amministrazione

Quando la forma del dashboard è stata creata, raccogli 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 riferimento al CI per l'admin API con l'URL di download da --output-record / build last-output.

Sicurezza

Autenticare ogni webhook (x-webhook-secretHMAC firma, o mTLS).
Elenco consentiti platform, mode, e ref In entrambi il proxy e il workflow validate Tratta il job — client_payload come un input non affidabile.
Passa i valori accettati attraverso le variabili di ambiente / gli output del job; 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.
context: Pagina/Area: Capgo Builder / prodotto di costruzione cloud nativa. Ruolo: Copia del sito. Visto in: pagina native-build.astro. Messaggio chiave `native_build_builder_build_minutes` (Minuti di costruzione del costruttore di costruzioni native). release to a protected GitHub Environment (as in the sample) or require an extra confirmation flag checked in validate.

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

GitHub configurazione delle azioni I nomi dei segreti e l'esportazione delle credenziali utilizzati da questi flussi di lavoro.

Auto OTA o Nativo Scegliere l'aggiornamento in tempo reale o nativo automaticamente al push su Git.