GitLab Webhook to Jenkins: Event-Driven CI/CD Pipeline Setup Guide

Why Switch from Polling to Webhook?

Traditional SCM polling makes Jenkins periodically check GitLab (e.g., every minute), wasting resources and introducing latency. Webhook flips the model: GitLab pushes an HTTP POST to Jenkins immediately when code is pushed or a merge request occurs, enabling near-instant builds.

End-to-End Flow

Developer pushes to GitLab repository k8s-dashboard.

GitLab wraps the event as JSON and POSTs to the configured Webhook URL.

Jenkins job has “Build when a change is pushed to GitLab” enabled.

Jenkins validates the X-Gitlab-Token header against the job’s Secret Token.

On match, the job runs: checkout, Maven build, test, deploy.

Two prerequisites: Jenkins must be reachable from GitLab (host IP or Docker service name), and the job must have the correct trigger and credentials configured.

Docker-Compose Networking

Jenkins runs in a container listening on port 8080. GitLab (self-hosted at http://192.168.145.129) can call Jenkins via host IP: http://192.168.145.129:8080/jenkins/ If both share a Docker network, the service name http://jenkins:8080/jenkins/ works, provided GitLab’s container can resolve it. Connectivity tests:

docker exec -it jenkins bash

ping 192.168.145.129

curl -I http://192.168.145.129/

Security: Secret Token

Set a Secret Token in GitLab project Webhook settings.

GitLab sends it as X-Gitlab-Token header.

Jenkins GitLab Plugin verifies the token matches the job’s generated value.

Mismatch → build rejected.

Plugin used: GitLab Plugin (provides “Build when a change is pushed to GitLab”, auto-generates trigger URL, parses payload).

Common Baseline

Repo: ssh://[email protected]:2222/root/k8s-dashboard.git Jenkins SSH credential: gitlab-ssh-cred JDK & Maven pre-configured in Jenkins Global Tool Configuration ( Maven3.9.10, JDK11).

Method 1: Freestyle Job

Job Configuration

New Freestyle job: k8s-dashboard-freestyle-webhook.

SCM: Git, repo URL above, credential gitlab-ssh-cred, branch main.

Build Trigger: check “Build when a change is pushed to GitLab” → Advanced → Generate Secret Token (e.g., 3c218abcdfc90281a27126917bbf3311). Save job.

Jenkins displays Webhook URL:

http://192.168.145.129:8080/jenkins/project/k8s-dashboard-freestyle-webhook

.

Build Step: Use Maven Tool, Not Shell

Avoid “Execute shell” calling mvn directly; the container may lack mvn on PATH, causing mvn: not found. Instead, add build step “Invoke top-level Maven targets”:

Maven Version: Maven3.9.10 (from Global Tools)

Goals: clean verify -DskipTests=false POM: default or project path.

GitLab Webhook Setup

Project → Settings → Webhooks → Add webhook.

URL: paste Jenkins Webhook URL.

Secret Token: copy the exact token generated in Jenkins (do not hand-type).

Trigger events: Push events (optionally Merge request events).

Save → Test → Push events; verify Jenkins receives build request.

Troubleshooting

Invalid url given : GitLab admin must enable Allow requests to the local network from webhooks and integrations under Admin → Settings → Network → Outbound requests.

HTTP 403 anonymous is missing the Job/Build permission : Usually token mismatch. Fix: regenerate token in Jenkins job (Build Triggers → Advanced → Generate), save job, copy new token to GitLab Webhook, retest.

Verification

Push a commit to main.

Job triggers immediately.

Console shows Git checkout and Maven build.

Method 2: Pipeline Job

Assumes existing Pipeline job ( k8s-dashboard-pipeline-webhook) with Jenkinsfile, Maven/JDK tools already configured. No pipeline logic changes needed.

Open job → Build Triggers → check “Build when a change is pushed to GitLab” → Advanced → Generate Secret Token (e.g., 55069b614d617335aff1ef4ab796035f). Save.

Copy Webhook URL:

http://192.168.145.129:8080/jenkins/project/k8s-dashboard-pipeline-webhook

.

GitLab Webhook: same URL, same token, Push events.

Push to main → job triggers, runs existing Jenkinsfile stages.

Method 3: Shared Library ( my-shared-lib@main )

If the Pipeline already uses a shared library (e.g., standardized gitCheckout, mavenBuild, sonarScan, quality gate), only the trigger needs adding.

@Library('my-shared-lib@main') _

pipeline {

agent any

tools {

jdk 'JDK11'

maven 'Maven3.9.10'

}

environment {

GIT_URL = 'ssh://[email protected]:2222/root/k8s-dashboard.git'

BRANCH_NAME = 'main'

SONAR_PROJECT_KEY = 'k8s-dashboard'

}

stages {

stage('📥 标准化代码拉取') {

steps {

script {

gitCheckout(

repoUrl: GIT_URL,

branch: BRANCH_NAME,

credentialsId: 'gitlab-ssh-cred',

depth: 1

)

}

}

}

stage('🔨 标准化 Maven 构建') {

steps {

script {

mavenBuild(

goals: 'clean verify',

skipTests: false

)

}

}

}

stage('🔍 调用共享库 Sonar 扫描') {

steps {

script {

sonarScan(

projectKey: SONAR_PROJECT_KEY,

projectName: 'k8s-dashboard',

sonarServer: 'sonarqube',

mavenGoals: 'clean verify'

)

}

}

}

stage('⏱ 质量门检查') {

steps {

timeout(time: 2, unit: 'MINUTES') {

script {

waitForQualityGate abortPipeline: true

}

}

}

}

}

post {

success { echo '✅ k8s-dashboard 代码扫描通过' }

failure { echo '❌ 构建或扫描失败' }

}

}

Trigger configuration identical to Method 2. Advantage: changing Git strategy or Maven params only requires updating the shared library; Webhook wiring stays untouched.

Summary & Best Practices

Key Value of This Change

Builds become event-driven → near-instant feedback.

Eliminates wasteful polling → less resource consumption.

Existing Jenkinsfile, shared library, Sonar, quality gates remain intact — no rework.

Webhook model aligns with real team workflows; easier to extend to deploy, notify, canary.

Critical Configuration Points

GitLab must allow outbound requests to local network (else Invalid url given).

Jenkins trigger enabled + Secret Token generated via Generate button (not manual).

GitLab Webhook Secret Token must match Jenkins token exactly (else HTTP 403 anonymous is missing the Job/Build permission).

Freestyle jobs must use “Invoke top-level Maven targets” to leverage Global Tool Maven; shell mvn fails if not on container PATH.

Recommended Rollout Order

Verify job builds manually (Git, JDK, Maven, Sonar all work).

Add GitLab trigger + generated Secret Token to Jenkins job.

Configure GitLab Webhook; run Test → Push events to validate URL, permissions, token, network.

Do a real git push; confirm auto-trigger, checkout, build.

When to Just Add Trigger vs. Standardize

Stable Freestyle/Pipeline jobs + only need auto-build on push → just add Webhook trigger.

Multiple services duplicating Git/Maven/Sonar/notify logic → extract shared library; ROI appears at scale.

Webhook solves who triggers ; shared library solves how to build . They are related but independent.

Result: k8s-dashboard moves from “Jenkins polls for changes” to “GitLab notifies Jenkins on change.” Combined with prior SonarQube scanning and quality-gate enforcement, a production-grade event-driven CI pipeline is now in place.