Déclencher des builds Jenkins avec des Webhooks

Introduction

Les intégrations par webhook permettent aux systèmes de gestion de versions de notifier Jenkins lorsqu'un dépôt est modifié. Un véritable webhook GitHub ou GitLab envoie une requête HTTP à Jenkins. Pour garantir la fiabilité de ce laboratoire, vous simulerez cette requête localement à l'aide de curl au lieu de dépendre d'un service externe.

Dans ce laboratoire, vous allez créer un dépôt Git local, configurer un job Jenkins de type Freestyle acceptant des paramètres de branche et de commit de style webhook, envoyer une requête de webhook locale et inspecter le journal du build déclenché.

Préparer un dépôt source local

Dans cette étape, vous allez créer un petit dépôt Git qui servira de système de gestion de versions. Un webhook transporte normalement la branche et le commit ayant subi des modifications ; vous enregistrerez donc ces valeurs pour les étapes suivantes.

La commande git init -b main crée un dépôt avec une branche main. Les commandes git config définissent l'identité de l'auteur afin que le commit puisse être créé sans invite de commande.

cd /home/labex/project
mkdir -p webhook-repo
cd webhook-repo
git init -b main
git config user.email "labex@example.com"
git config user.name "LabEx Webhook"

Créez un fichier et validez-le (commit) :

echo "webhook demo build" > app.txt
git add app.txt
git commit -m "Add webhook demo app"

Enregistrez la branche et l'identifiant court du commit dans un fichier d'environnement. La commande tee écrit les valeurs dans un fichier tout en les affichant pour que vous puissiez les vérifier.

COMMIT=$(git rev-parse --short=12 HEAD)
BRANCH=$(git branch --show-current)
printf 'WEBHOOK_BRANCH=%s\nWEBHOOK_COMMIT=%s\n' "$BRANCH" "$COMMIT" | tee /home/labex/project/webhook-values.env

La sortie devrait ressembler à ceci :

WEBHOOK_BRANCH=main
WEBHOOK_COMMIT=...

Le job Jenkins s'exécutera à l'intérieur du conteneur Docker Jenkins. Copiez le dépôt dans /var/jenkins_home/webhook-repo afin que le processus de build puisse le lire depuis l'intérieur de ce conteneur :

docker exec jenkins rm -rf /var/jenkins_home/webhook-repo
docker cp /home/labex/project/webhook-repo jenkins:/var/jenkins_home/webhook-repo
docker exec -u root jenkins chown -R jenkins:jenkins /var/jenkins_home/webhook-repo

Créer un job Jenkins paramétré

Dans cette étape, vous allez créer un job Jenkins de type Freestyle nommé webhook-trigger-demo. Le job acceptera deux paramètres de chaîne : WEBHOOK_BRANCH et WEBHOOK_COMMIT. Cela reflète les données importantes envoyées par un webhook de gestion de versions.

Créez le fichier XML de configuration du job Jenkins. La commande shell dans le job affiche la branche et le commit, puis vérifie que le commit existe dans le dépôt Git local.

cat > /home/labex/project/webhook-trigger-demo-config.xml <<'XML'
<?xml version='1.1' encoding='UTF-8'?>
<project>
  <actions/>
  <description>Build triggered by a local webhook payload.</description>
  <keepDependencies>false</keepDependencies>
  <properties>
    <hudson.model.ParametersDefinitionProperty>
      <parameterDefinitions>
        <hudson.model.StringParameterDefinition>
          <name>WEBHOOK_BRANCH</name>
          <description>Branch name from the webhook payload.</description>
          <defaultValue>main</defaultValue>
          <trim>true</trim>
        </hudson.model.StringParameterDefinition>
        <hudson.model.StringParameterDefinition>
          <name>WEBHOOK_COMMIT</name>
          <description>Commit id from the webhook payload.</description>
          <defaultValue></defaultValue>
          <trim>true</trim>
        </hudson.model.StringParameterDefinition>
      </parameterDefinitions>
    </hudson.model.ParametersDefinitionProperty>
  </properties>
  <scm class="hudson.scm.NullSCM"/>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers/>
  <concurrentBuild>false</concurrentBuild>
  <builders>
    <hudson.tasks.Shell>
      <command>set -e
echo "Webhook branch: $WEBHOOK_BRANCH"
echo "Webhook commit: $WEBHOOK_COMMIT"
echo "Source repository: /var/jenkins_home/webhook-repo"
git -C /var/jenkins_home/webhook-repo rev-parse --verify "$WEBHOOK_COMMIT^{commit}"
git -C /var/jenkins_home/webhook-repo show --no-patch --format='Commit subject: %s' "$WEBHOOK_COMMIT"</command>
      <configuredLocalRules/>
    </hudson.tasks.Shell>
  </builders>
  <publishers/>
  <buildWrappers/>
</project>
XML

Copiez le job dans Jenkins et rechargez le contrôleur avec le script utilitaire créé lors de la configuration :

docker exec jenkins mkdir -p /var/jenkins_home/jobs/webhook-trigger-demo
docker cp /home/labex/project/webhook-trigger-demo-config.xml jenkins:/var/jenkins_home/jobs/webhook-trigger-demo/config.xml
/home/labex/project/reload-jenkins.sh

Confirmez que Jenkins peut voir le job :

curl -fsS http://localhost:8080/job/webhook-trigger-demo/api/json | grep -o '"name":"webhook-trigger-demo"'

La sortie attendue est :

"name":"webhook-trigger-demo"

Créer un fichier de charge utile (payload) de webhook

Dans cette étape, vous allez créer un fichier JSON qui ressemble à une petite charge utile de webhook de gestion de versions. Les vraies charges utiles contiennent de nombreux champs. Ce laboratoire ne conserve que les champs nécessaires au build : ref pour la branche et after pour l'identifiant du commit.

Chargez les valeurs de branche et de commit enregistrées, puis écrivez la charge utile JSON :

cd /home/labex/project
source webhook-values.env
cat > local-webhook-payload.json <<JSON
{
  "ref": "refs/heads/${WEBHOOK_BRANCH}",
  "after": "${WEBHOOK_COMMIT}",
  "repository": {
    "full_name": "labex/webhook-demo"
  }
}
JSON

Utilisez l'outil de formatage JSON de Python pour confirmer que le fichier est valide et lisible :

python3 -m json.tool /home/labex/project/local-webhook-payload.json

Vous devriez voir la référence de branche refs/heads/main et l'identifiant du commit provenant de votre dépôt Git.

Envoyer la requête de webhook avec curl

Dans cette étape, vous allez simuler la livraison du webhook. Jenkins utilise un jeton "crumb" pour protéger les requêtes POST ; la commande demande donc d'abord un crumb et stocke le cookie correspondant. Ensuite, elle envoie la branche et le commit en tant que paramètres de build à buildWithParameters.

Extrayez la branche et le commit de la charge utile JSON vers un fichier d'environnement shell :

python3 - <<'PY' > /tmp/webhook-trigger.env
import json
from pathlib import Path

payload = json.loads(Path("/home/labex/project/local-webhook-payload.json").read_text())
branch = payload["ref"].split("/")[-1]
commit = payload["after"]
print(f"WEBHOOK_BRANCH={branch}")
print(f"WEBHOOK_COMMIT={commit}")
PY
source /tmp/webhook-trigger.env

Envoyez maintenant la requête de build à Jenkins :

CRUMB=$(curl -fsS -c /tmp/jenkins-webhook-build.cookies 'http://localhost:8080/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)')
curl -fsS -b /tmp/jenkins-webhook-build.cookies -H "$CRUMB" \
  --data-urlencode "WEBHOOK_BRANCH=${WEBHOOK_BRANCH}" \
  --data-urlencode "WEBHOOK_COMMIT=${WEBHOOK_COMMIT}" \
  -X POST http://localhost:8080/job/webhook-trigger-demo/buildWithParameters

Attendez que le build #1 soit terminé :

until curl -fsS http://localhost:8080/job/webhook-trigger-demo/1/api/json >/tmp/webhook-build-1.json 2>/dev/null && grep -q '"building":false' /tmp/webhook-build-1.json; do
  echo "Waiting for webhook build #1..."
  sleep 3
done

Confirmez que le build a réussi :

curl -fsS http://localhost:8080/job/webhook-trigger-demo/1/api/json | grep -o '"result":"SUCCESS"'

Inspecter le journal du build déclenché

Dans cette étape, vous allez inspecter la sortie de la console Jenkins. Le journal de build est la preuve la plus directe que la charge utile du webhook a bien atteint le job, car il affiche la branche, l'identifiant du commit et le sujet du commit.

Affichez les lignes pertinentes de la console :

curl -fsS http://localhost:8080/job/webhook-trigger-demo/1/consoleText | grep -E 'Webhook branch|Webhook commit|Commit subject'

La sortie doit inclure la branche main et le sujet du commit :

Webhook branch: main
Webhook commit: ...
Commit subject: Add webhook demo app

Ouvrez Firefox depuis l'interface de bureau et visitez http://localhost:8080/job/webhook-trigger-demo/1/console. La page de sortie de la console (Console Output) devrait afficher la branche du webhook, l'identifiant du commit et le sujet du commit dans le journal de build.

Sortie de la console de build Jenkins par webhook

Résumé

Vous avez créé un dépôt Git local, configuré un job Jenkins pour accepter des paramètres de build de type webhook, envoyé une requête de webhook locale avec curl, et vérifié les preuves de la branche et du commit dans le journal de build Jenkins. Il s'agit du même flux de base utilisé par les systèmes de gestion de versions lorsqu'ils notifient Jenkins des changements dans un dépôt.