Pourquoi les webhooks GitHub expirent face à un Jenkins derrière un VPN
GitHub envoie les webhooks vers l’intérieur, donc un VPN qui protège Jenkins les refuse. Faites sortir la livraison via un relay, ou remplacez le webhook par un agent qui interroge.
La page de livraison affiche un délai d’attente et Jenkins ne journalise rien, ce qui est la signature d’une connexion qui n’est jamais arrivée. GitHub envoie un webhook sous forme de HTTP POST sortant depuis sa propre infrastructure vers l’URL de payload que vous avez configurée. Un VPN protège Jenkins en refusant exactement ce type de connexion. Rien n’est cassé d’un côté comme de l’autre. Le problème est la direction de la requête.
Ce que la livraison tente réellement
GitHub résout le nom d’hôte de l’URL de payload et s’y connecte depuis l’internet public. Si cette URL pointe vers une adresse privée, ou vers un nom qui ne se résout qu’à l’intérieur de votre réseau, la tentative échoue avant qu’aucune requête ne soit faite. Si elle pointe vers un nom public que votre edge écarte, la tentative expire à la place.
Cette distinction compte pour le diagnostic. Un échec DNS et un port filtré ressemblent tous deux à rien du côté de Jenkins, et tous deux apparaissent sur GitHub comme une livraison échouée avec une raison différente jointe. Lisez cette raison avant de changer l’URL.
Un tunnel qui compose vers l’extérieur ne crée pas d’écouteur. C’est la partie que les gens s’attendent à voir fonctionner autrement.
Trois façons de corriger la direction de la connexion
Chaque solution change qui initie la connexion, et il n’existe que trois formes.
| Approach | Who initiates | What you give up |
|---|---|---|
| Relay service | An outbound client inside the network | A third party sees every payload |
| Reverse tunnel or ingress | The public edge, into a controlled listener | An inbound surface you must secure |
| Runner or polling | The agent, outbound to GitHub | Instant delivery, replaced by a schedule |
L’interrogation est la moins élégante et la plus simple à exploiter. Un relay maintient un retour quasi instantané sans ouvrir de port. Un runner est généralement la bonne réponse quand la confidentialité du payload exclut un tiers, car la tâche peut tourner sur une machine déjà située dans le réseau.
Choisissez selon ce que vous pouvez exploiter, pas selon ce qui sonne moderne.
Faire sortir une livraison avec smee
Créez un canal sur le service de relay et conservez son URL. À l’intérieur du réseau, installez le client et transmettez les livraisons vers le chemin que Jenkins attend. L’URL de payload dans les réglages du dépôt devient l’URL du canal, avec le type de contenu réglé sur application/json.
sudo npm install --global smee-client
smee -u CHANNEL_URL --path /github-webhook/ --port 8080Trois détails décident si cela fonctionne. Le chemin doit correspondre à ce que Jenkins attend pour les événements GitHub, qui est /github-webhook/ par défaut. Jenkins doit écouter sur le port que vous avez donné au client. Et l’URL Jenkins configurée dans la tâche doit concorder avec ce chemin, sinon l’événement arrive puis est jeté.
Une barre oblique finale qui ne correspond pas produit une 404 qui se lit comme un échec de livraison et n’en est pas un.
L’exécuter pour qu’il survive à la semaine
Un client au premier plan meurt avec le terminal, et les webhooks fonctionnent un jour puis s’arrêtent. Donnez-lui une unit avec Restart=always, exécutez-la en tant qu’utilisateur Jenkins et lisez le journal après la première livraison réelle. C’est cette dernière étape qui sépare un relay qui fonctionne d’un relay configuré.
[Unit]
Description=smee webhook relay
After=network.target
[Service]
Type=simple
Restart=always
RestartSec=2
User=jenkins
ExecStart=/usr/bin/smee -u CHANNEL_URL --path /github-webhook/ --port 8080
[Install]
WantedBy=multi-user.targetTestez avec un vrai push plutôt qu’avec un bouton de rejeu. Un rejeu exerce le payload stocké du relay, pas le chemin de GitHub à votre canal, il peut donc passer alors que la livraison en direct échoue encore.
Alertez quand l’unit s’arrête. Un relay à l’arrêt est silencieux par construction, et le silence est exactement ce que vous déboguez déjà.
Ce que le relay peut voir, et quand ne pas en utiliser un
Un relay termine le payload, il voit donc les noms de dépôts, les données de commit et tout ce que l’événement transporte. Traitez l’URL du canal comme un point de terminaison public. Gardez le token secret de Jenkins configuré pour que les livraisons forgées soient rejetées, et limitez le token utilisé par Jenkins au minimum nécessaire.
Si la confidentialité du payload l’exclut, un runner auto-hébergé ou un tunnel inverse authentifié est la réponse.
Un relay est désormais de l’infrastructure, et il mérite la même revue que le build qu’il déclenche. Faites tourner le canal s’il fuit, et notez la date à laquelle vous avez vérifié pour la dernière fois une livraison en direct. Mettez cette date dans le runbook à côté de l’URL du canal. Un relay que personne n’a examiné pendant un an est un point de terminaison public que personne ne possède.