Activar compilaciones nativas mediante webhook

Copie un comando de configuración 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óno CMS, o portal interno a menudo desean un solo webhook HTTP: presiona un botón en su propia interfaz de usuario, y comienza un paquete de construcción nativo firmado. Este guía muestra el patrón estándar — una llamada HTTP autenticada delgada a su host code, que ejecuta el mismo flujo de trabajo de construcció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ú haces no necesitas Capgo para exponer un webhook de “build” público. Tu CI ya tiene los secretos de firma; el webhook solo tiene que iniciar ese trabajo de CI de manera segura.

Requisitos previos

Un flujo de trabajo Capgo Build que ya funciona desde la IU de CI o en empuje (acciones de GitHub)
Permiso para crear un token GitHub detallado, token de disparador de GitLab o equivalente
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 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 empezar a trabajar en una nueva característica revisa y antes de cualquier paso que contenga secretos. Pasa los valores aceptados a través de los resultados de la tarea / variables de entorno — nunca interpola 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_dispatch) Almacénalo solo en tu backend administrativo — nunca en el navegador.

3. Llame al webhook desde su panel de administración

Su backend (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`	Deben 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 usuario administrativa (‘Crear aplicaciones nativas’). La consola solo necesita llegar a su backend; el backend almacena GITHUB_TOKEN.

Precaución

If the admin tool can only POST to a URL you control (Zapier, Make, Cloudflare Worker, Express route), put a short proxy in front of 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,
    })
  },
}

Si la herramienta administrativa solo puede enviar un POST a una URL que controla (Zapier, Make, __CAPGO_KEEP_0__ Worker, ruta de Express), coloque un proxy corto frente a __CAPGO_KEEP_1__:

Copiar a portapapeles (clipboard en inglés, pero se tradujo a copiar a portapapeles para mantener la traducción natural para el usuario cultural contexto, adaptando el idioma y el tono para el contexto de la página.) Then configure the admin product: ‘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: el panel almacena una URL y un secreto; 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 disparador bajo Configuración → CI/CD → Tokens de disparador de pipeline, luego desde la consola administrativa:

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 eventos o expandir la tarea en una matriz paralela de la misma manera que el ejemplo de GitHub.

Bitbucket y Azure

Plataforma	Mecanismo de webhook
Bitbucket	URL de disparador de pipeline o contraseña de pipeline personalizada + contraseña de app `POST`
Azure DevOps	Pipeline de ejecución REST API con una PAT; utilice la pipeline manual desde Desencadenante desde la interfaz de usuario de CI

El patrón es idéntico: administrador → su secreto verificación → anfitrión API → Capgo Tarea de compilación.

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

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

Plataforma — ios / android / ambos
Modo --- depuración (QA) o lanzamiento (tienda)
Referencia Git --- rama o etiqueta para construir
Actor --- correo electrónico o id de usuario para registros de auditoría (transmitir) client_payload)

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

Seguridad

Autenticar cada webhook (x-webhook-secretHMAC firma, o mTLS).
Lista de permisos platform, mode, y ref en ambos el proxy y el flujo de trabajo validate trate client_payload como entrada no confiable.
Envíe 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 delimitados a un solo repositorio.
Limitar la velocidad del proxy; los builds nativos cuestan minutos de construcción.
context: Página/área: Capgo Builder / página de producto de build nativo en la nube. Rol: Copia de sitio web. Visto en: página native-build.astro. Mensaje clave `native_build_builder_build_minutes` (Native Build Builder Build Minutes). release to a protected GitHub Environment (as in the sample) or require an extra confirmation flag checked in validate.

Activar desde la IU de CI Same Capgo Build job, started from the Actions / Pipelines tab.

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.