Installer Jenkins et créer ses jobs : controller, agents, credentials et déclencheurs

Jenkins exécute des builds depuis 2011 et ne montre aucun signe de disparition, surtout parce qu'il sait tout automatiser : il n'a pas d'avis sur votre langage, votre système d'exploitation ou votre cible de déploiement, et son écosystème de plugins couvre à peu près tous les outils dont un build a jamais eu besoin. Cette souplesse est aussi sa faiblesse. Une installation par défaut est un serveur d'automatisation sans authentification qui exécute des commandes shell arbitraires, et une instance Jenkins qui a grandi au fil de l'eau pendant cinq ans n'est souvent qu'un empilement de jobs configurés à la main que plus personne n'ose toucher.

Ce guide met en place l'inverse : un controller à la sécurité saine, un travail qui s'exécute sur des agents plutôt que sur le serveur lui-même, des credentials dans le magasin prévu à cet effet et une configuration que vous pouvez reconstruire. Il suppose que vous savez déjà pourquoi vous voulez de l'intégration continue ; l'objectif ici est une installation fonctionnelle et défendable, ainsi que le vocabulaire pour l'exploiter.

Les briques et leur articulation

Une installation Jenkins comporte trois éléments.

Le controller est l'application web. Il sert l'interface et l'API REST, stocke la configuration et l'historique des builds, planifie les builds et héberge les plugins. Il ne devrait rien builder lui-même.

Un agent (l'ancienne documentation parle de « slave », et certains champs de plugins le font encore) est une machine ou un conteneur qui exécute les builds. Chaque agent annonce un nombre d'executors — des slots de build concurrents — et un ensemble de labels comme linux, jdk21 ou docker. Les jobs demandent un label, et Jenkins les planifie sur un agent correspondant disposant d'un executor libre.

Un job — Jenkins parle désormais d'items — est une unité d'automatisation : un pipeline, un projet freestyle, un pipeline multibranch, un dossier qui les regroupe. Tout ce qu'un job produit pendant une exécution se trouve dans un workspace, un répertoire sur l'agent réutilisé d'un build à l'autre pour le même job sur le même agent.

Le controller et les agents communiquent via une connexion TCP qui transporte un protocole de remoting. Deux sens sont possibles : le controller se connecte à l'agent en SSH, ou l'agent se connecte au controller sur un port dédié. Le choix relève du pare-feu, pas des fonctionnalités.

Installer le controller

Jenkins se décline en une version hebdomadaire et une ligne LTS ; les versions LTS reçoivent des correctifs rétroportés pendant douze semaines et ce sont elles qu'il faut faire tourner en production. La ligne LTS 2.5x exige Java 17 ou 21 — le support de Java 11 a pris fin il y a des années et les versions les plus récentes refusent de démarrer dessus.

L'image de conteneur est la voie la plus rapide et laisse l'hôte propre :

docker volume create jenkins_home

docker run -d --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  --restart unless-stopped \
  jenkins/jenkins:lts-jdk21

Le port 8080 sert l'interface web ; le 50000 est le port des agents inbound, à publier uniquement si des agents se connectent au controller. Le volume nommé est le JENKINS_HOME, et c'est le seul état qui compte : si vous pouvez restaurer ce volume, vous pouvez restaurer Jenkins.

Sur un hôte Linux, l'installation par paquet place JENKINS_HOME dans /var/lib/jenkins et tourne sous systemd avec l'utilisateur jenkins :

sudo apt-get install -y openjdk-21-jre fontconfig
# add the Jenkins apt repository and key as documented, then:
sudo apt-get install -y jenkins
sudo systemctl enable --now jenkins
systemctl status jenkins

Dans les deux cas, la première page demande une clé de déverrouillage affichée dans le log et stockée dans secrets/initialAdminPassword :

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
# or, for a package install
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Acceptez les plugins suggérés, créez le premier compte administrateur avec un vrai mot de passe et renseignez correctement l'URL de Jenkins : les plugins construisent leurs liens à partir d'elle, et une valeur erronée produit des webhooks et des e-mails qui ne pointent nulle part.

Verrouiller l'instance

Un Jenkins fraîchement installé ne peut pas être exposé tel quel. Parcourez cette liste avant que quiconque d'autre n'obtienne un compte.

1. Placer TLS en frontal

   Faites tourner Jenkins derrière nginx ou un autre reverse proxy qui termine le HTTPS. Jenkins sait servir du TLS lui-même, mais un proxy vous apporte le renouvellement des certificats, HTTP/2 et un endroit où ajouter du rate limiting. Configurez le proxy pour transmettre les en-têtes d'hôte et de schéma d'origine, sinon Jenkins signalera que sa configuration de reverse proxy est cassée.

2. Choisir un security realm

   La base d'utilisateurs intégrée suffit pour une poignée de personnes. Au-delà, branchez LDAP, Active Directory ou un fournisseur SAML/OIDC via un plugin, pour que quitter l'entreprise supprime l'accès. N'activez jamais l'inscription libre sur une instance joignable depuis l'extérieur.

3. Passer à l'autorisation matricielle

   Le réglage par défaut « les utilisateurs connectés peuvent tout faire » est pratique et mauvais. La sécurité matricielle, ou une stratégie par rôles avec le plugin Role Strategy, permet d'accorder la lecture à tous, le build aux développeurs et l'administration à deux personnes. Attribuez les permissions à des groupes, pas à des individus.

4. Mettre les executors du controller à zéro

   Manage Jenkins → Nodes → Built-In Node → réglez le nombre d'executors sur 0. Les builds n'ont alors nulle part où tourner sauf sur les agents, et c'est précisément le but.

5. Laisser actives la protection CSRF et la script security

   Les deux sont activées par défaut, et les deux sont parfois désactivées par quelqu'un qui débogue une intégration. Aucune ne doit rester coupée. Le Groovy que les pipelines exécutent hors sandbox doit être approuvé explicitement dans In-process Script Approval.

6. Appliquer les correctifs selon un calendrier

   Jenkins et ses plugins publient régulièrement des avis de sécurité. Abonnez-vous au flux des avis, appliquez les mises à jour de plugins chaque mois et les montées de version LTS au moins chaque trimestre. Un Jenkins non patché ayant un accès réseau à la production est un risque sérieux.

Ajouter des agents

L'agent durable le plus simple est un hôte Linux accessible en SSH. Préparez-le avec un JRE et les outils de build nécessaires, créez un utilisateur jenkins avec un répertoire personnel et ajoutez la clé publique du controller à son authorized_keys. Puis, dans Manage Jenkins → Nodes → New Node, choisissez un agent permanent et renseignez :

• Remote root directory — un répertoire de travail comme /home/jenkins/agent, avec beaucoup d'espace disque. C'est là que vivent les workspaces.
• Labels — descriptifs et précis : linux jdk21 maven docker. Les jobs sélectionnent les agents par expression de labels, donc linux && docker fonctionne.
• Usage — « use this node as much as possible », ou « only build jobs with label expressions matching this node » pour du matériel spécialisé.
• Launch method — Launch agents via SSH, en pointant vers l'hôte avec le credential SSH que vous avez stocké dans Jenkins.

Pour les agents derrière un pare-feu qui n'accepte aucune connexion entrante, utilisez plutôt la méthode inbound. Le controller vous fournit une ligne de commande à lancer sur l'agent :

java -jar agent.jar \
  -url https://jenkins.example.com/ \
  -secret @/etc/jenkins/agent-secret \
  -name build-node-2 \
  -workDir /home/jenkins/agent

Faites-la tourner sous systemd pour qu'elle se reconnecte après un redémarrage. Une troisième option, celle qui passe le mieux à l'échelle, ce sont les agents éphémères : le plugin Docker ou Kubernetes démarre un conteneur neuf pour chaque build et le détruit ensuite, si bien qu'aucun état ne fuit d'un build à l'autre et qu'il n'y a aucun agent à patcher. Cela coûte un peu de temps de démarrage par build, et le jeu en vaut la chandelle dès que vous dépassez une poignée de jobs.

Credentials

Ne mettez jamais un mot de passe dans la configuration d'un job, dans un script de build ou dans une variable d'environnement saisie dans l'interface. Jenkins dispose d'un magasin de credentials, chiffré avec une clé située dans JENKINS_HOME/secrets, et tous les plugins qui ont besoin d'un secret y puisent.

Les credentials ont un type — nom d'utilisateur et mot de passe, clé privée SSH, secret text (pour les tokens d'API), secret file, certificat — et une portée. La portée globale rend un credential visible par tous les jobs ; la portée système le réserve à Jenkins lui-même, par exemple pour une clé de connexion d'agent. Stockez les credentials dans un dossier plutôt qu'en global dès qu'une équipe possède un groupe de jobs : un credential rattaché à un dossier est invisible pour les jobs extérieurs, et c'est la forme d'isolation la moins coûteuse que propose Jenkins.

Chaque credential a un ID. Donnez-lui un identifiant stable et parlant — nexus-deploy, github-app-ci — car c'est cet ID que référence la configuration des jobs :

withCredentials([usernamePassword(credentialsId: 'nexus-deploy',
                                  usernameVariable: 'NEXUS_USER',
                                  passwordVariable: 'NEXUS_PASS')]) {
    sh 'mvn -s settings.xml deploy'
}

Jenkins masque les valeurs dans le log de console, mais ce masquage est un filet de sécurité, pas une garantie : un script qui encode un secret en base64 et l'affiche le laissera fuiter. Privilégiez des credentials aux droits les plus restreints possible et renouvelez-les à intervalles réguliers.

Les jobs freestyle et pourquoi les pipelines les ont remplacés

Un projet freestyle se configure entièrement via des formulaires web : gestion du code source, déclencheurs de build, étapes de build, actions post-build. En créer un est instructif, car cela montre l'anatomie d'un build.

Créez un nouveau Freestyle project, puis :

• Source Code Management — Git, avec l'URL du dépôt et un credential ; indiquez la branche.
• Build Steps — « Invoke top-level Maven targets » avec les goals clean verify, ou « Execute shell » avec les commandes que vous lanceriez en local.
• Post-build Actions — publiez les résultats JUnit depuis **/target/surefire-reports/*.xml, archivez target/*.jar, envoyez un e-mail en cas d'échec.

Ce job fonctionne et se crée en cinq minutes. Ses limites apparaissent vite. La configuration n'existe que dans le XML du controller : elle n'est donc pas versionnée avec le code et ne passe par aucune revue. Elle ne permet pas d'exprimer une suite de stages avec du parallélisme et une promotion conditionnelle. Elle ne survit pas à une reconstruction du controller, sauf si vous avez restauré tout le JENKINS_HOME. Et chaque branche exige un job dupliqué.

Un job pipeline règle ces quatre problèmes en déplaçant la définition dans un Jenkinsfile commité avec le code source. Le build est alors relu comme du code, chaque branche porte son propre pipeline, et un controller peut être reconstruit à partir de rien en faisant pointer de nouveaux jobs vers les dépôts. Réservez les jobs freestyle aux petites tâches de maintenance ; utilisez des pipelines pour tout ce qui construit un produit. Le guide du Jenkinsfile couvre la syntaxe en détail.

Déclencher les builds

Quatre déclencheurs couvrent pratiquement tous les cas.

Les webhooks sont le bon choix par défaut. L'hébergeur Git appelle https://jenkins.example.com/github-webhook/ (ou l'endpoint de webhook générique) à chaque push, et le build démarre en moins d'une seconde, sans polling inutile. Il faut pour cela que le controller soit joignable depuis l'hébergeur Git, ce qui, dans un réseau privé, implique généralement un chemin d'entrée sur liste blanche.

Le polling SCM demande au dépôt si quelque chose a changé, selon un planning comme H/5 * * * *. C'est la solution de repli quand les webhooks sont impossibles. Le H est une extension propre à Jenkins qui signifie « répartir ce job dans l'intervalle d'après le hachage de son nom » : les interrogations s'étalent au lieu que tous les jobs frappent le serveur à la minute pile.

Les builds planifiés (H 2 * * *) s'exécutent qu'il y ait eu des changements ou non, ce qui convient aux suites d'intégration nocturnes, aux scans de vulnérabilités des dépendances ou aux longs tests de performance.

Les déclencheurs amont lancent un job quand un autre se termine, formant une chaîne. Au sein d'un même pipeline, les stages les remplacent ; entre dépôts — une bibliothèque qui déclenche ses consommateurs — ils restent utiles.

Plugins, mises à jour et configuration as code

Tout ce que fait Jenkins, il le fait à travers des plugins, qui sont aussi son principal risque opérationnel : chacun est du code qui s'exécute avec tous les privilèges, et un plugin abandonné par son auteur devient bloquant à la montée de version Java suivante. Gardez la liste courte : installez ce dont un job a besoin, désinstallez ce que plus rien ne référence et vérifiez les mises à jour selon un calendrier plutôt que lorsque quelque chose casse.

Les plugins que presque toutes les installations utilisent : Pipeline (la suite workflow-aggregator), Git, Credentials Binding, Matrix Authorization, JUnit, Warnings Next Generation, Docker Pipeline et Configuration as Code.

Ce dernier mérite qu'on s'y attarde. JCasC permet de placer la configuration du controller lui-même dans un fichier YAML, si bien que l'instance peut être recréée au lieu d'être restaurée :

jenkins:
  systemMessage: "Managed by configuration as code — do not edit through the UI"
  numExecutors: 0
  mode: EXCLUSIVE
  securityRealm:
    local:
      allowsSignup: false
  authorizationStrategy:
    globalMatrix:
      entries:
        - group:
            name: "authenticated"
            permissions: ["Overall/Read", "Job/Read"]
        - group:
            name: "developers"
            permissions: ["Job/Build", "Job/Cancel"]
unclassified:
  location:
    url: "https://jenkins.example.com/"
    adminAddress: "[email protected]"

Faites pointer la variable d'environnement CASC_JENKINS_CONFIG vers ce fichier, gardez-le dans Git, et la configuration du controller devient révisable en revue de code. Ajoutez-y une liste de plugins aux versions figées, et une reconstruction devient l'affaire d'un quart d'heure.

Sauvegardes et disque

Tout ce que Jenkins sait se trouve sous JENKINS_HOME. Une sauvegarde qui couvre les *.xml de premier niveau, jobs/*/config.xml, users/, nodes/ et — c'est crucial — secrets/ suffit à reconstruire l'instance. L'historique des builds et les workspaces sont volumineux et en grande partie jetables ; exclure jobs/*/builds et workspace garde la sauvegarde assez légère pour tourner chaque nuit.

#!/usr/bin/env bash
set -euo pipefail
JENKINS_HOME=${JENKINS_HOME:-/var/lib/jenkins}
STAMP=$(date +%F)
tar -czf "/backup/jenkins-${STAMP}.tar.gz" \
    -C "$JENKINS_HOME" \
    --exclude='jobs/*/builds' \
    --exclude='workspace' \
    --exclude='caches' \
    . 

Chiffrez l'archive : elle contient le répertoire secrets et, avec lui, tous les credentials que détient Jenkins. Puis testez une restauration au moins une fois : une sauvegarde que personne n'a jamais restaurée n'est qu'une hypothèse.

Le disque est l'autre problème récurrent. Définissez une politique de rétention des builds sur chaque job et nettoyez les workspaces sur les agents qui hébergent de nombreux jobs ; un controller à court de disque corrompt la configuration des jobs au moment de l'écriture.

Erreurs courantes

• Lancer les builds sur le controller. Cela donne à chaque build un accès en lecture à tous les credentials et fait tomber le serveur dès qu'un test consomme toute la mémoire.
• Tout configurer à coups de clics. Au bout d'un an, plus personne ne sait pourquoi un job fonctionne. Déplacez la logique de build dans un Jenkinsfile et les réglages du controller dans JCasC.
• Des secrets collés dans les étapes de build. Ils finissent dans le XML des jobs, dans les sauvegardes et dans les logs de console. Utilisez le magasin de credentials et withCredentials.
• Ne jamais mettre à jour. Les avis de sécurité du core et des plugins s'accumulent, et sauter quatre versions LTS d'un coup est bien plus difficile que d'en passer une par trimestre.
• Un historique de builds illimité. La rétention par défaut conserve tout indéfiniment, et les logs de console ajoutés aux artefacts archivés finiront par remplir le disque.
• Un seul agent géant partagé. Les jobs se disputent les ports, les caches et le disque. Les agents conteneurs éphémères éliminent toute une catégorie de mystères du genre « ça n'échoue que sur le nœud 3 ».
• Pas de responsable. Un Jenkins que tout le monde utilise et que personne n'entretient se dégrade inévitablement. Désignez un responsable et donnez-lui du temps pour s'en occuper.

Points clés à retenir

• Faites tourner la ligne LTS sur Java 17 ou 21, réservez le controller à la planification et à l'interface, et mettez son nombre d'executors à zéro.
• Sécurisez l'instance avant de l'ouvrir : TLS via un proxy, un vrai security realm, l'autorisation matricielle, la protection CSRF et la script security laissées actives, et un calendrier de correctifs.
• Les agents se connectent soit en sortie via SSH, soit en entrée sur le port des agents ; les agents Docker ou Kubernetes éphémères offrent des builds propres sans machines à entretenir.
• Placez chaque secret dans le magasin de credentials, rattachez-le à un dossier quand c'est possible et référencez-le par un ID stable.
• Les jobs freestyle sont une démonstration utile de cinq minutes ; les pipelines définis dans un Jenkinsfile versionné sont ce que doit utiliser l'automatisation en production.
• Déclenchez par webhook quand c'est possible, rabattez-vous sinon sur le polling réparti par hachage, et utilisez les builds planifiés pour le travail nocturne.
• JENKINS_HOME est tout le système : sauvegardez-le en incluant secrets/, chiffrez l'archive, plafonnez la rétention des builds et gardez la configuration reproductible avec JCasC.