Activar compilaciones nativas mediante webhook

Copiar una línea de comando con los pasos de instalación y la guía de markdown completa para este plugin.

Capgo La compilación se inicia normalmente desde una laptop o un trabajo de CI. Los equipos que envían desde una pantalla de administración, CMS o portal interno a menudo desean una sola Webhook HTTP: presione un botón en su propia interfaz de usuario, y un compilado nativo firmado comienza. Este guía muestra el patrón estándar — una llamada HTTP autenticada delgada a su code host, que ejecuta el mismo flujo de trabajo de compilación Capgo que ya utiliza.

Arquitectura

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

Tú No necesitas Capgo para exponer un webhook de “build” público. Ya que tu CI tiene los secretos de firma; el único trabajo del webhook es iniciar ese trabajo de CI de manera segura.

Requisitos previos

Un flujo de trabajo Capgo Build que ya funciona desde la interfaz de usuario de CI o al recibir un push (GitHub Acciones)
Permiso para crear un token GitHub fino-grano, token de disparador de GitLab o equivalente
A un secreto compartido que su panel de administración enviará (cabecera o cuerpo)

Opción A — GitHub `repository_dispatch` (recomendado)

GitHub acepta una llamada autenticada de API que inicia un flujo que escucha por repository_dispatch. Cualquier panel que pueda POST JSON puede dispararlo.

1. Flujo que escucha por el webhook

Validar el payload antes de context client_payload directamente en run: scripts (orientación de inyección de 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 de acceso personal detallado (o token de instalación de la aplicación GitHub) con Contenido: Leer y escribir en el repositorio (requerido para repository_dispatchAlmacénalo solo en tu backend de administración — nunca en el navegador.

3. Llama al webhook desde tu panel de administración

Su back-end (no el navegador del usuario) debe enviar:

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	Propósito
`event_type`	Debe coincidir `types` en el flujo de trabajo (`capgo-native-build`)
`client_payload.platform`	`ios`, `android`o `both`
`client_payload.mode`	`debug` o `release`
`client_payload.ref`	Rama o etiqueta para construir (opcional)

Conecte el mismo JSON POST a un botón en su interfaz de administración (“Construir aplicaciones nativas”). El panel solo necesita llegar suyo backend; el backend almacena GITHUB_TOKEN.

Opción B — Tiny proxy webhook (cualquier host)

Si la herramienta de administración solo puede enviar un POST a una URL que controla (Zapier, Make, Cloudflare Worker, ruta de Express), coloque un proxy corto frente 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,
    })
  },
}

Luego configure el producto de administración:

Configuración	Valor
URL	`https://your-worker.example.com/native-build`
Método	`POST`
Cabecera	`x-webhook-secret: <shared secret>`
Cuerpo	`{ "platform": "both", "mode": "release" }`

Esta es la forma habitual para conectar un webhook a un panel de administración en línea: el panel almacena una URL y un secreto; los Capgo credenciales permanecen en GitHub Acciones.

Desencadenante de flujo de trabajo de GitLab

GitLab expone tokens de desencadenante de flujo de trabajo que son objetivos webhooks naturales.

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

Crear un token de desencadenante en Configuración → CI/CD → Tokens de disparo de pipeline, luego desde la consola de administración:

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

Para ambas plataformas, se pueden disparar dos triggers o expandir el trabajo en una matriz paralela de la misma manera que el ejemplo GitHub.

Bitbucket y Azure

Plataforma	Mecanismo de webhook
Bitbucket	URL de disparo de pipeline o contraseña de pipeline personalizada + contraseña de aplicación `POST`
Azure DevOps	Pipeline run REST API con una PAT; utilice el flujo de trabajo de pipeline manual desde Desencadenante desde la interfaz de usuario de CI

El patrón es idéntico: admin → su verificación secreta → host API → Capgo Tarea de compilación.

Lista de verificación de carga útil para herramientas de administración

Cuando se construye la forma de la consola, recolecte al menos:

Plataforma — ios / android / ambos
Modo — depuración (QA) o de liberación (almacenamiento)
Referencia Git — rama o etiqueta para construir
Actor — correo electrónico o ID de usuario para registros de auditoría (transmite) client_payload)

Opcional: después de la ejecución, que la CI envíe de vuelta al administrador API con la URL de descarga desde --output-record / build last-output.

Seguridad

Autenticar cada webhook (x-webhook-secretHMAC, firma o mTLS)
Lista blanca platform, modey ref en ambos el proxy y el flujo de trabajo validate job — trata client_payload como una entrada no confiable.
Pase los valores aceptados a través de variables de entorno / salidas de trabajo; no intercale campos de pago en run: scripts.
Mantenga los tokens GitHub/GitLab en el lado del servidor solo.
Preferir tokens limitados a un solo repositorio.
Limitar la velocidad del proxy; los builds nativos cuestan minutos de build.
contexto: Página/área: Capgo Builder / producto de build nube nativa. Rol: Copia de sitio web. Visto en: página native-build.astro. Mensaje clave `native_build_builder_build_minutes` (Minutos de build del constructor de builds nativos). release to a protected GitHub Environment (as in the sample) or require an extra confirmation flag checked in validate.

Título de sección: ‘Guías relacionadas’ Misma Capgo tarea de compilación, iniciada desde la pestaña Acciones / Pipelines.

GitHub configuración de Acciones Exportación de credenciales y nombres de secretos utilizados por estos flujos de trabajo.

Auto OTA o Nativo Al hacer push en Git, elige actualización en vivo vs nativa automáticamente.