Activar compilaciones nativas mediante webhook

Copie 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 un solo Webhook HTTP: presiona un botón en su propia interfaz de usuario, y un compilación nativa firmada comienza. Este manual muestra el patrón estándar — una llamada HTTP autenticada delgada a su host code, 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ú haces no necesitas Capgo para exponer un webhook de “build” público. Tu CI ya 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 IU de CI o en función de la notificación (GitHub Acciones)
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 API autenticada que inicia un flujo de trabajo que escucha para repository_dispatch. Cualquier panel que pueda POST JSON puede dispararlo.

1. Flujo de trabajo que escucha el webhook

Validar el payload antes de trabajar en una nueva característica Revisa y antes de cualquier paso que requiera 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 scripts).

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 de administración — 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`	Deberá 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`	o la rama o etiqueta para construir (opcional)

Conecta el mismo JSON POST a un botón en tu interfaz de usuario administrativa (‘Crear aplicaciones nativas’). La consola solo necesita llegar a tu 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 controlas (Zapier, Make, __CAPGO_KEEP_0__ Worker, ruta de Express), coloca un proxy corto frente a __CAPGO_KEEP_1__:

Copiar a portapapeles (clipboard en inglés, pero se tradujo a portapapeles para mantener la traducción natural en español, ya que el portapapeles es más común en español que el clipboard en este contexto). Entonces configura el producto administrativo: ‘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, dispara dos disparadores o expande el trabajo en una matriz paralela de la misma manera que el ejemplo GitHub.

Bitbucket y Azure

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

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

Lista de verificación de pago 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 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 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 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 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.
Preferir tokens limitados 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 nato en la nube. Rol: Copia de sitio web. Visto en: página native-build.astro. Mensaje clave `native_build_builder_build_minutes` (Minutos de construcción del constructor de builds nativos). release to a protected GitHub Environment (as in the sample) or require an extra confirmation flag checked in validate.

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

GitHub Actions setup Los nombres de credenciales y secretos utilizados por estos flujos de trabajo.

Auto OTA o Nativo Actualiza en vivo vs nativo automáticamente al hacer push en Git.