De ce webhookurile GitHub expiră împotriva unui Jenkins din spatele unui VPN
GitHub trimite webhookurile spre interior, așa că un VPN care protejează Jenkins le refuză. Redirecționează livrarea spre exterior printr-un relay sau înlocuiește webhookul cu un agent care interoghează.
Pagina de livrare arată un timeout și Jenkins nu înregistrează nimic, ceea ce este semnătura unei conexiuni care nu a ajuns niciodată. GitHub trimite un webhook ca un HTTP POST de ieșire din propria infrastructură către payload URL-ul pe care l-ai configurat. Un VPN protejează Jenkins refuzând exact acel tip de conexiune. Nimic nu este stricat de niciuna dintre părți. Problema este direcția cererii.
Ce încearcă de fapt livrarea
GitHub rezolvă numele de gazdă din payload URL și se conectează la el din internetul public. Dacă acel URL indică o adresă privată sau un nume care se rezolvă doar în interiorul rețelei tale, încercarea eșuează înainte de a fi făcută vreo cerere. Dacă indică un nume public pe care marginea ta îl aruncă, încercarea expiră în schimb.
Distincția contează pentru diagnostic. O defecțiune DNS și un port filtrat arată amândouă ca și cum nimic nu s-a întâmplat pe partea Jenkins, și amândouă apar pe GitHub ca o livrare eșuată cu un motiv diferit atașat. Citește acel motiv înainte de a schimba URL-ul.
Un tunel care formează numărul spre exterior nu creează un ascultător. Exact acea parte oamenii se așteaptă să funcționeze altfel.
Trei moduri de a corecta direcția conexiunii
Fiecare soluție schimbă cine inițiază conexiunea, și există doar trei forme.
| 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 |
Interogarea este cea mai puțin elegantă și cea mai ușor de operat. Un relay menține feedback aproape instantaneu fără a deschide un port. Un runner este de obicei răspunsul corect când confidențialitatea payload-ului exclude o terță parte, pentru că lucrarea poate rula pe o mașină care se află deja în rețea.
Alege după ce poți opera, nu după ce sună modern.
Redirecționează o livrare spre exterior cu smee
Creează un canal pe serviciul de relay și păstrează URL-ul acestuia. În interiorul rețelei, instalează clientul și redirecționează livrările către calea pe care o așteaptă Jenkins. Payload URL-ul din setările depozitului devine URL-ul canalului, cu tipul de conținut setat la application/json.
sudo npm install --global smee-client
smee -u CHANNEL_URL --path /github-webhook/ --port 8080Trei detalii decid dacă funcționează. Calea trebuie să corespundă cu ceea ce așteaptă Jenkins pentru evenimentele GitHub, care implicit este /github-webhook/. Jenkins trebuie să asculte pe portul pe care l-ai dat clientului. Și Jenkins URL-ul configurat în job trebuie să fie de acord cu acea cale, altfel evenimentul ajunge și apoi este aruncat.
O nepotrivire a barei oblice finale produce un 404 care se citește ca o livrare eșuată și nu este.
Rularea astfel încât să supraviețuiască săptămânii
Un client în prim-plan moare odată cu terminalul, iar webhookurile funcționează o zi și apoi se opresc. Dă-i un unit cu Restart=always, rulează-l ca utilizator Jenkins și citește jurnalul după prima livrare reală. Exact acel ultim pas separă un relay funcțional de unul configurat.
[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.targetTestează cu un push real în locul unui buton de redare. O redare exersează payload-ul stocat al relay-ului, nu calea de la GitHub la canalul tău, așa că poate trece în timp ce livrarea live încă eșuează.
Alertează când unit-ul se oprește. Un relay căzut este silențios prin construcție, iar tăcerea este exact ceea ce depanezi deja.
Ce poate vedea relay-ul și când să nu folosești unul
Un relay termină payload-ul, așa că vede nume de depozite, date de commit și orice altceva transportă evenimentul. Tratează URL-ul canalului ca pe un endpoint public. Păstrează tokenul secret Jenkins configurat pentru ca livrările falsificate să fie respinse, și limitează tokenul folosit de Jenkins la minimul necesar.
Dacă confidențialitatea payload-ului exclude asta, un runner găzduit propriu sau un tunel invers autentificat este răspunsul.
Un relay este acum infrastructură și merită aceeași revizuire ca build-ul pe care îl declanșează. Rotește canalul dacă se scurge și notează data la care ai verificat ultima dată o livrare live. Pune acea dată în runbook lângă URL-ul canalului. Un relay pe care nimeni nu l-a revizuit un an este un endpoint public pe care nimeni nu îl deține.