El webhook de GitHub no llega al Jenkins privado: corrija la ruta

Puede abrir Jenkins por la VPN y aun así ver que GitHub informa de un webhook fallido, porque son dos conexiones distintas con dos responsables distintos. El navegador viaja por un túnel que negoció su portátil; el servicio de entrega de GitHub parte de internet pública y no tiene ruta hacia la red privada. El acceso al repositorio no cambia eso, aunque Jenkins pueda obtener del mismo repositorio sin problemas. Elija un punto de entrada, un relé o el sondeo, y luego pruebe la ruta que sigue realmente el evento.

Una sesión de navegador solo demuestra una dirección

Una conexión VPN responde a una pregunta: puede este portátil llegar al host interno. La entrega de webhooks pregunta otra: puede un servicio externo abrir una conexión hacia ese host. Que Jenkins obtenga de un repositorio es tráfico de salida y no dice nada sobre la accesibilidad entrante. Mantenga ambas direcciones en líneas separadas de su diagrama, incluido qué lado inicia cada una.

Lea el registro de entrega antes de cambiar nada. Un tiempo de espera agotado, un restablecimiento de conexión y una solicitud aceptada que no coincidió con ninguna tarea tienen tres responsables distintos: red, proxy y configuración del disparador.

Opción A: exponer un punto de entrada estrecho

Si la organización ya publica un punto de entrada aprobado, exponga la ruta del webhook en lugar del panel. Normalmente eso significa una regla de proxy inverso que acepta POST en la URL del gancho y los reenvía a Jenkins mientras la interfaz de administración sigue inaccesible desde fuera.

curl -sS -o /dev/null -w "%{http_code}\n" -X POST https://jenkins.example.com/github-webhook/

Ejecute esa prueba desde una red sin acceso VPN, porque un éxito desde dentro del túnel no demuestra nada. El punto de entrada debería rechazar las solicitudes sin el secreto compartido, que GitHub envía como cabecera de firma, y aceptar solo la única ruta y el único método que publicó. Una consola de Jenkins pública no es una solución para el webhook; es un incidente esperando al siguiente escáner. Acote la regla lo suficiente para que el resto de la aplicación conserve los controles de acceso que tenía.

Opción B: invertir la dirección con un relé

Donde no se aprobará la exposición entrante, un cliente pequeño dentro de la red puede mantener una conexión de salida hacia un relé y recibir los eventos reenviados. El relé pasa entonces a formar parte de la ruta de entrega, así que su disponibilidad y su autenticación importan tanto como la tarea de compilación.

ssh -N -R 9000:localhost:8080 relay.example.net

La guía de Jenkins sobre webhooks detrás de cortafuegos describe esta forma, y vale la pena leerla antes de escribir un reenviador propio. Termine el TLS en el relé, verifique la firma antes de que el evento llegue a la tarea y vigile el enlace de salida, porque un túnel caído parece exactamente un evento que nunca se envió. Confirme también que el relé conserva el cuerpo de la solicitud byte a byte, ya que las comprobaciones de firma fallan con JSON que se ha analizado y vuelto a codificar por el camino.

Opción C: sondear el repositorio

El sondeo cambia latencia por simplicidad y no necesita ninguna ruta de entrada. Jenkins puede sondear según un horario, o una tarea pequeña puede consultar la API e iniciar una compilación cuando ve una revisión desconocida.

curl -sS -u "$USER:$TOKEN" "https://api.github.com/repos/OWNER/REPO/commits?per_page=1"

Cada sondeo gasta llamadas a la API y añade un retraso entre el push y la compilación, algo que se nota en repositorios concurridos y en límites de velocidad compartidos. También necesita credenciales guardadas donde se ejecute el sondeador, así que limite el token a acceso de solo lectura al repositorio y rótelo como cualquier otro secreto. Elíjalo cuando el volumen de eventos sea bajo o cuando nunca se vaya a aprobar un punto de entrada, y dígalo en la descripción de la tarea para que nadie se pregunte después por qué las compilaciones van con retraso.

Acepte una entrega real, no una carga de página

Elija la opción que elija, la prueba de aceptación es un evento enviado por la plataforma de origen, no una pestaña del navegador abierta desde un portátil con privilegios. Haga push de un commit vacío a una rama temporal y lea el código de respuesta de la entrega, el registro del relé o la salida de la tarea de sondeo, en ese orden. Un 200 del punto de entrada sin compilación significa que el filtro del disparador está mal; un tiempo de espera significa que la ruta sigue cerrada. Anote cuál de los tres diseños se usa, porque de lo contrario la siguiente persona que depure repetirá la prueba del navegador y llegará al mismo callejón sin salida.

Aplique el mismo razonamiento a las devoluciones de pago y a otras notificaciones externas: cada una necesita su propia ruta hacia la aplicación privada, incluso cuando todo el mundo ya tiene una sesión VPN. La ruta de entrega pertenece al diseño de la aplicación, no a una nota al pie sobre redes.