Howto Jenkins

Compatibilité des versions
Installation
Configuration
- Modifier le répertoire temporaire de Jenkins
- Configuration Reverse proxy Apache en HTTPS
Dépannage
- Problème de configuration de Reverse Proxy
Agents
- Installation
- Configuration
Lien avec une forge

Documentation : https://jenkins.io/doc/
Ansible : https://gitea.evolix.org/evolix/ansible-roles/src/branch/stable/jenkins
Statut de cette page : test / bookworm

Jenkins est un outil open source d’intégration continue écrit en Java. Jenkins peut fonctionner dans un conteneur de servlets tel qu’Apache Tomcat, ou en mode autonome avec son propre serveur Web embarqué.

Compatibilité des versions

On recommande en :

Debian 8 avec du Java 7 et une version inférieure à 2.54 de Jenkins
Debian 9 avec du Java 8 et une version supérieure à 2.54 de Jenkins
Debian 10 avec du Java 11 et une version supérieure à 2.164.1 de Jenkins
Debian 11 avec du Java 11 et une version supérieure à 2.332.1 de Jenkins
Debian 12 avec du Java 17 et une version supérieure à 2.361.1 de Jenkins

Notons qu’il n’est pas compatible avec Java 9 et 10.

Installation

Jenkins n’est pas disponible dans les dépôts Debian, il faut donc ajouter le dépôt comme suit :

# curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | tee \
/etc/apt/keyrings/jenkins-keyring.asc > /dev/null

# echo deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc] \
https://pkg.jenkins.io/debian-stable binary/ | tee \
/etc/apt/sources.list.d/jenkins.list > /dev/null

Ensuite on procède à l’installation:

# apt update
# apt install fontconfig openjdk-17-jre
# apt install jenkins

Configuration

Par défaut Jenkins utilise le port 8080, pour modifier cela, il faut modifier le fichier /etc/default/jenkins et modifier la ligne suivante :

HTTP_PORT=8080

Le /home de jenkins se trouve dans :

/var/lib/jenkins/

Il faut créer par exemple la clé SSH de jenkins dans ce répertoire, en se connectant avec l’utilisateur jenkins.

su - jenkins

Puis générer la clé SSH.

ssh-keygen -t ed25519

Modifier le répertoire temporaire de Jenkins

Souvent la partition /tmp est en noexec, ce qui pose des problèmes a Jenkins lors d’un clonage de dépôt où il y a besoin d’exécuter un script sh

On peut modifier le dossier tmp dans /var/lib/jenkins/tmp et bien donner comme propriétaire jenkins:jenkins au dossier tmp

Il faut ensuite mettre la configuration suivant dans /etc/default/jenkins :

# use a different tmpdir for jenkins
JAVA_ARGS="$JAVA_ARGS -Djava.io.tmpdir=/var/lib/jenkins/tmp/"

Pour le que dossier tmp soit vidé au redémarrage de la machine, comme un vrai dossier /tmp, il faut le monter en tmpfs dans /etc/fstab :

tmpfs                   /var/lib/jenkins/tmp        tmpfs    defaults,nosuid,nodev,size=1024m  0       0

Configuration Reverse proxy Apache en HTTPS

Voici une configuration d’un VirtualHost Apache pour proxyfier Jenkins en HTTPS (nécessite d’activer les modules proxy et proxy_http d’Apache) :

<VirtualHost *:80>
    ServerName jenkins.domaine.com
    Redirect permanent / https://jenkins.domaine.com/
</VirtualHost>
<VirtualHost *:443>
    ServerName jenkins.domaine.com
    ServerAdmin webmaster@localhost

    <Directory proxy:http://localhost:8080/*>
	Require all granted
    </Directory>

    ProxyRequests     Off
    ProxyPreserveHost On
    AllowEncodedSlashes NoDecode

    <Location />
        ProxyPass http://localhost:8080/ nocanon retry=0
        ProxyPassReverse http://localhost:8080/
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Forwarded-Port "443"
    </Location>

   CustomLog /var/log/apache2/access_jenkins.log combined
   ErrorLog /var/log/apache2/error_jenkins.log

    SSLEngine on
    SSLProtocol all -SSLv2 -SSLv3
    SSLCertificateFile /etc/ssl/certs/foo.crt
    SSLCertificateKeyFile /etc/ssl/private/bar.key
    SSLCertificateChainFile /etc/ssl/certs/DigiCertCA.crt

</VirtualHost>

Dépannage

Problème de configuration de Reverse Proxy

Si sur la page d’administration de Jenkins l’erreur suivante apparaîtra :

La configuration de votre proxy inverse n'est pas bonne

Il faut configurer le ProxyPass avec l’option nocanon comme ceci :

<Location />
        ProxyPass http://localhost:8080/ nocanon
        ProxyPassReverse http://localhost:8080/
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Forwarded-Port "443"
 </Location>

Si une réponse 403 est renvoyée lors de l’envoi d’un formulaire, activer l’option de compatibilité (« Enable proxy compatibility ») de protection CSRF dans « Manage Jenkins > Security > Configure Global Security > CSRF Protection » (ou « Administrer Jenkins -> Sécurité -> Configurer la sécurité globale -> CSRF Protection -> Activer la compatibilité proxy ») peut aider.

Agents

L’exécution des tests ne devrait pas être réalisée sur le nœud intégré, il faut donc paramétrer des agents, qui seront connectés au contrôleur dont l’installation vient d’être décrite. C’est sur ces nœuds que s’exécuterons effectivement les tests.

Installation

D’après le projet amont, Java est nécessaire pour faire fonctionner les agents (mais il y a moyen de s’en passer comme décrit par Debian).

Docker est pratique aussi pour certaines constructions. Cela nécessite l’installation des plugins Docker et Docker Pipeline sur le contrôleur.

# apt install default-jre-headless docker.io

Configuration

Création de l’utilisateur que l’instance principale contactera pour exécuter les tests.

# adduser --disabled-password jenkins
# adduser jenkins docker

Ajouter la partie publique de la clef configurée précédemment à ~jenkins/.ssh/authorized_key. Il peut être intéressant de vérifier que l’on arrive bien à se connecter depuis le contrôleur à l’agent par SSH dès maintenant.

Déclarer l’agent dans le contrôleur

Le nœud peut maintenant être ajouté depuis l’interface web de Jenkins.

Build Executor Status (en bas à gauche)
> New node (en haut à gauche)
  > Node name (configurer un nom explicite, par exemple celui de la machine)
  > Type > Permanent Agent
  > Create
    > Remote root directory > /home/jenkins
    > Launch method > Launch agents via SSH
    > Host > nom de la machine (FQDN)
    > Crédentials > Add
      > Kind > SSH Username with private key
      > Username > jenkins
      > Private key > Enter directly > Add > La clef privée déjà créé sur la machine
      > Save

Lien avec une forge

Maintenant que l’agent est connecté, il est possible de configurer une forge contenant les dépôts que l’on souhaite tester.

Pour se connecte à Gitea (par exemple), l’installation d’un plugin Gitea est nécessaire. Cela peut être réalisé dans l’interface web de Jenkins.

Manage Jenkins
> Manage Plugins
  > Available
    > Search > Gitea
      > Gitea Plugin (cocher la case de la colonne « Install » initiale)
      > Install without restart
        > Restart Jenkins when installation is complete and no jobs are running

Dans Gitea, il faut créer un utilisateur (par exemple « jenkins ») et lui donner accès aux organisations et dépôts que l’on souhait tester (par exemple en l’ajoutant aux équipes existantes, ou en créant une nouvelle équipe, par exemple « ci »). Une fois connecté en tant que ce nouvel utilisateur dans Gitea, il faut créer un jeton.

Profiles and Settings… (tout en haut à droite)
> Settings
  > Applications
    > Manage Access Tokens > Generate Token (noter le jeton)

Dans Jenkins, l’organisation correspondante peut être créée et associée.

New Item
> Enter an item name (par exemple l’URL de la forge)
  > Organisation Folder
  > OK
    > Projects
      > Repository Sources
        > Add
          > Gitea Organization
            > Credentials
              > Add
                > Kind
                  > Gitea Personnal Access Token
                    > Token (choisir le jeton qui vient d’être défini)
                    > Add
                  > Owner (indiquer le nom d’utilisateur correspondant à l’espace qui sera surveillé, exécuté…)
                  > Save

Dans Jenkins, tous les dépôts de l’utilisateur précédent peuvent être surveillés, et tout ceux contenant un fichier .Jenkinsfile (Jenkinsfile par défaut, le choix ici est de rendre le fichier caché comme dans de nombreux autres outils de CI) seront automatiquement testés. Il faut préalablement sélectionner l’organisation précédente. Basic Branch Build Strategies permet de déclencher les constructions à base de tags.

Configure
  > Projects
    > Repository Sources
      > Gitea Organization
        > Behaviours > Add > Discover Tags
        > Project Recognizers > Pipeline Jenkinsfile > Script Path > .Jenkinsfile
        > Build strategies > Add > Tags
        > Build strategies > Add > Regular branches (sinon on ne construit plus grand chose…)

Si nécessaire (par exemple si les évènements capturés sont insuffisant), il est possible d’augmenter la fréquence de de découverte des dépôts, branches et fichiers .Jenkinsfile dans le même menu.

Configure
   > Scan Gitea Organization Triggers
     > 5 minutes
   > Child Scan Triggers
     > 5 minutes