Configura webhooks

En esta página, se describe cómo configurar webhooks en Secure Source Manager.

Los webhooks son solicitudes HTTP que se activan por un evento en Secure Source Manager y se envían a una URL especificada por el usuario.

Antes de comenzar

  1. Crea una instancia de Secure Source Manager.
  2. Crea un repositorio de Secure Source Manager.

Roles obligatorios

Para obtener los permisos que necesitas para crear webhooks, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Para obtener información sobre cómo otorgar roles de Secure Source Manager, consulta Control de acceso con IAM y Otorga acceso a la instancia a los usuarios.

Configura un webhook

Console

  1. En la interfaz web de Secure Source Manager, navega al repositorio para el que deseas crear un webhook.
  2. Haz clic en Configuración.
  3. Haz clic en Webhooks y, luego, en Agregar webhook.

  4. En el campo ID de webhook, ingresa un ID para el webhook.

  5. En el campo URL de destino, ingresa la URL del webhook. Por ejemplo, si deseas activar una compilación en Jenkins, puedes configurar un activador de webhook y, luego, ingresar la URL del activador de Jenkins aquí para activar tu compilación en Jenkins.

  6. En la sección Activador, selecciona una de las siguientes opciones:

    • Push: Se activa cuando se envía un push al repositorio.
    • Pull request state changed: Se activa cuando cambia el estado de la solicitud de extracción.

  7. Configura la autenticación de webhook con una cadena de consulta sensible o la autenticación de cuenta de servicio:

    • Cadena de consulta sensible:

      Tu cadena de consulta sensible consta de los valores key y secret de la URL de tu webhook, incluidos los prefijos key= y secret=. Para configurar la autorización de cadenas de consulta sensibles, debes quitar estos valores de la URL de tu webhook y agregarlos al campo Cadena de consulta sensible:

      1. Borra ? de la URL del webhook.
      2. Copia la parte restante de la URL, que comienza con key=.
      3. Pega esta parte en el campo Cadena de consulta sensible.
      4. Borra la misma parte de la URL del webhook.

      Por ejemplo, dada la siguiente URL: https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

      Tu cadena de consulta sensible sería la siguiente: key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

    • Autenticación de la cuenta de servicio:

      1. Verifica que tu repositorio tenga una cuenta de servicio con los roles de IAM definidos para la autenticación de la cuenta de servicio en Roles obligatorios.
      2. Selecciona Habilitar la autenticación de la cuenta de servicio.

  8. Si seleccionaste Push, puedes ingresar una lista de entidades permitidas para los eventos push en el campo Filtro de rama.

    El campo Branch filter usa el patrón glob, y solo las operaciones en las ramas que coincidan activarán una compilación. Por ejemplo, {main,dev} se activa en los eventos de envío a las ramas main y dev. Si el campo está vacío o es *, se informan los eventos de envío para todas las ramas. Para obtener información sobre la sintaxis, consulta la documentación de glob.

  9. Haz clic en Add webhook (Agregar webhook).

  10. El webhook se muestra en la página Webhooks.

REST

Para crear un webhook, invoca el método hooks.create con una solicitud POST al extremo hooks. Puedes autenticar tu webhook con una cadena de consulta sensible o con la autenticación de cuenta de servicio.

  • Cadena de consulta sensible

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook?key=${KEY}&secret=${SECRET}",
    "events": ["PUSH"]
    "sensitiveQueryString": "${SENSITIVE_QUERY_STRING_VALUE}"
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

    Tu SENSITIVE_QUERY_STRING_VALUE debe ser el valor de key y secret en la URL de tu webhook. Por ejemplo, si tu key es eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf y tu secret es MySecret, tu SENSITIVE_QUERY_STRING_VALUE debe ser key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=MySecret.

  • Autenticación de cuenta de servicio

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook",
    "events": ["PUSH"],
    "serviceAccountAuth": true
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

Prueba tu webhook

  1. En la página Webhooks de Secure Source Manager, haz clic en el webhook que deseas probar.

  2. Ve al final de la página y haz clic en Probar entrega.

    Se agrega un evento de marcador de posición a la cola de entrega. Es posible que tarde unos segundos en aparecer en el historial de entrega.

  3. También puedes usar un comando git para enviar o combinar una solicitud de extracción y probar el webhook.

  4. Verifica el estado de la compilación o el evento activado en el historial de compilaciones del servicio en el que configuraste el activador de webhook.

  5. También puedes ver la Solicitud y la Respuesta a la entrega de prueba en la sección Entregas recientes de la página de webhook de Secure Source Manager después de enviar tu primera entrega de prueba.

Sustituye las variables de YAML de Cloud Build por datos de carga útil

Si usas webhooks para conectarte a Cloud Build, puedes sustituir las variables de YAML de Cloud Build por datos de la carga útil del webhook de Secure Source Manager.

  1. En la página Webhooks de Secure Source Manager, en la sección Recent deliveries, haz clic en la primera fila.

    Se muestran el encabezado y el contenido de la solicitud que se envían con la carga útil del webhook.

  2. Navega al panel de Cloud Build y, luego, haz clic en Activadores.

  3. Haz clic en el activador que quieras configurar.

  4. En la sección Avanzada, en Variables de sustitución, haz clic en + Agregar variable.

  5. Ingresa el nombre y el valor de la variable. El prefijo del valor es body.

    Por ejemplo, para sustituir _REPO_URL por el campo de datos de la carga útil repository.clone_url y _COMMIT_SHA por el SHA de la confirmación más reciente en el archivo YAML de Cloud Build, ingresa los siguientes nombres y valores:

    • Variable 1: _REPO_URL Valor 1: $(body.repository.clone_url)
    • Variable 2: _COMMIT_SHA Valor 2: $(body.after)

    El archivo YAML de Cloud Build es similar al siguiente:

    steps:
- name: gcr.io/cloud-builders/git
  env:
  - '_REPO_URL=$_REPO_URL'
  - '_COMMIT_SHA=$_COMMIT_SHA'
  script: |
    #!/bin/sh
    git clone ${_REPO_URL} /workspace
    cd /workspace
    git reset --hard ${_COMMIT_SHA}

¿Qué sigue?