Attivare costruzioni native tramite webhook

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

Capgo La costruzione è normalmente avviata da un laptop o un lavoro di CI. Le squadre che inviano da un dashboard amministrativo admin dashboardo CMS, o portale interno spesso desiderano un singolo webhook HTTP: premere un pulsante nella propria interfaccia utente, e iniziare un build nativo firmato. Questa guida mostra il modello standard — un chiamata autenticata HTTP sottile nella propria code host, che esegue lo stesso Capgo workflow di costruzione che già utilizza.

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 Capgo per esporre un webhook pubblico “di costruzione.” Il tuo CI già ha i segreti di firma; l'hook ha solo il compito di avviare quel lavoro di CI in modo sicuro.

Requisiti

Un flusso di lavoro Capgo Build che già funziona dalla interfaccia utente di CI o all'avvio (GitHub Azioni)
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 un chiamata autenticata API che avvia un flusso di lavoro che ascolta per repository_dispatch. Qualsiasi dashboard che POST può inviare JSON può attivarlo.

1. Flusso di lavoro che ascolta per il webhook

Valida il payload prima di iniziare a lavorare su una nuova feature, è consigliabile creare un issue e discuterne con il team prima di iniziare a lavorare su di esso. (traduzione di 'before') | Prima di iniziare a lavorare su una nuova feature, è consigliabile menzionare l'issue prima di iniziare a lavorare su di esso. checkout e prima di qualsiasi passo 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: scripts (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 nel repository (richiesto per repository_dispatchMemoralo solo nel tuo backend amministrativo — 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	Funzione
`event_type`	Deve corrispondere `types` nel flusso di lavoro (`capgo-native-build`)
`client_payload.platform`	`ios`, `android`o `both`
`client_payload.mode`	`debug` o `release`
`client_payload.ref`	o il branch o la tag da costruire (facoltativo)

Collega lo stesso JSON POST a un pulsante nella tua interfaccia 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 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	Pipeline di esecuzione REST API con un token di accesso; utilizzare il pipeline manuale da Trigger dal CI UI

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

Elenco dei controlli per il payload degli strumenti di amministrazione

Quando la form 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 postare sul API amministrativo 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 — trattalo client_payload come input non attendibile.
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.

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

GitHub Impostazioni azioni Esportazione delle credenziali e dei 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.