Varför GitHub-webhooks får timeout mot en Jenkins bakom en VPN
GitHub skickar webhooks inåt, så en VPN som skyddar Jenkins avvisar dem. Skicka leveransen utåt via en relay, eller ersätt webhooken med en agent som pollar.
Leveranssidan visar en timeout och Jenkins loggar ingenting, vilket är signaturen för en anslutning som aldrig kom fram. GitHub skickar en webhook som en utgående HTTP POST från sin egen infrastruktur till den payload-URL du konfigurerade. En VPN skyddar Jenkins genom att avvisa precis den sortens anslutning. Ingenting är trasigt på någon av sidorna. Problemet är riktningen på begäran.
Vad leveransen faktiskt försöker göra
GitHub slår upp värdnamnet i payload-URL:en och ansluter till det från det publika internet. Om den URL:en pekar på en privat adress, eller på ett namn som bara slås upp inne i ditt nätverk, misslyckas försöket innan någon begäran skickas. Om den pekar på ett publikt namn som din kant släpper, får försöket timeout i stället.
Skillnaden spelar roll för diagnostiken. Ett DNS-fel och en filtrerad port ser båda ut som om ingenting hände på Jenkins-sidan, och båda visas i GitHub som en misslyckad leverans med en annan orsak bifogad. Läs den orsaken innan du ändrar URL:en.
En tunnel som ringer utåt skapar ingen lyssnare. Det är den delen folk förväntar sig ska fungera annorlunda.
Tre sätt att rätta anslutningens riktning
Varje lösning ändrar vem som startar anslutningen, och det finns bara tre former.
| 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 |
Pollning är det minst eleganta och det enklaste att drifta. En relay håller nästan omedelbar återkoppling utan att öppna en port. En runner är oftast rätt svar när payload-konfidentialitet utesluter en tredje part, eftersom jobbet kan köras på en maskin som redan står inne i nätverket.
Välj efter vad du kan drifta, inte efter vad som låter modernt.
Skicka en leverans utåt med smee
Skapa en kanal på relay-tjänsten och behåll dess URL. Inne i nätverket installerar du klienten och vidarebefordrar leveranser till den sökväg Jenkins förväntar sig. Payload-URL:en i repoinställningarna blir kanalens URL, med innehållstypen satt till application/json.
sudo npm install --global smee-client
smee -u CHANNEL_URL --path /github-webhook/ --port 8080Tre detaljer avgör om det fungerar. Sökvägen måste matcha det Jenkins förväntar sig för GitHub-händelser, vilket som standard är /github-webhook/. Jenkins måste lyssna på porten du gav klienten. Och den Jenkins-URL som är konfigurerad i jobbet måste stämma med den sökvägen, annars kommer händelsen in och kastas sedan bort.
En avvikande avslutande snedstreck ger en 404 som läses som en misslyckad leverans och inte är det.
Köra det så att det överlever veckan
En klient i förgrunden dör med terminalen, och webhooks fungerar en dag och slutar sedan. Ge den en unit med Restart=always, kör den som Jenkins-användaren och läs journalen efter den första riktiga leveransen. Det sista steget är det som skiljer en fungerande relay från en konfigurerad.
[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.targetTesta med en riktig push i stället för en replay-knapp. En replay övar relayens lagrade payload, inte vägen från GitHub till din kanal, så den kan passera medan direktleveransen fortfarande misslyckas.
Larma när uniten stannar. En relay som ligger nere är tyst av konstruktion, och tystnaden är precis det du redan felsöker.
Vad relayen kan se, och när du inte bör använda en
En relay terminerar payloaden, så den ser reponamn, commit-data och allt annat händelsen bär. Behandla kanalens URL som en publik slutpunkt. Håll Jenkins hemliga token konfigurerad så att förfalskade leveranser avvisas, och begränsa den token Jenkins använder till det nödvändiga minimumet.
Om payload-konfidentialitet utesluter det, är en självhostad runner eller en autentiserad omvänd tunnel svaret.
En relay är infrastruktur nu, och den förtjänar samma granskning som bygget den utlöser. Rotera kanalen om den läcker, och notera datumet då du senast verifierade en direktleverans. Sätt det datumet i runbooken bredvid kanalens URL. En relay som ingen har granskat på ett år är en publik slutpunkt som ingen äger.