Tools4Jenkins is a Jenkins library which allows you to setup a jenkins infrastructure as code. This library is intertwined with Tools4Dev for configuration loading and job execution.
Before configuring nodes and jobs, you have to create some base configuration in jenkins.
Create credentials with
slave_default_useras ID. This will be used for slave SSH connection.Create credentials with
jenkins_git_credentialsas ID. This will be used to connect to Git repositories.Create a
_base_node with the following configuration :
Name : _base_
Remote root directory : HOME
Launch method : Launch agents via SSH
Host : IP_ADDRESS
Credentials : slave_default_user
Create a
_Base_folder at jenkins' rootInside
_Base_folder, create a_MultiBranchPipeline_multibranch pipeline with the following configuration :
Branch Sources : Git :
Project Repository : GIT_SOURCE
Credentials : jenkins_git_credentials
Behaviors : Filter by name (with regular expression) : Regular expression : GIT_BRANCH_FILTER
Property strategy : Suppress automatic SCM triggerring
Build Configuration :
Mode : by Jenkinsfile
Script Path : JENKINSFILE
Properties : Pipeline Libraries : Library :
Name : main
Branch : main
Retrieval method : Modern SCM
Source Code Management : Git :
Project Repository : LIB_SOURCE
Credentials : jenkins_git_credentials
Behaviors : Discover branches
This is the base config needed to automaticaly create the configuration you will define during the next step.
The file ci-example.xml contains the configuration of your nodes, projects and jobs to generate.
By editing this file, you will create your infrastructure at wks sync command invoke.
This allows you to recreate very rapidly your CI in the event of a catastrophic failure.
This uses the jenkins config you created at the previous step to generate jenkins config for your infrastructure.
configuration name="jenkins-lib" : add the git path to the Tools4Jenkins lib (unique)
configuration name="jenkins-root" : you might want to edit this if your jenkins path has been customised (unique)
node : add a node/agent (can be used multiple times) with a specific home and ip address (nodes will be linked to src/slaves/{XXX}.groovy more on that later)
repoGit : add a git repo for jobs (multiple) this will concat base, key and name to create the repo url
folder name="Home" : default job base folder, edit root= if your jenkins path has been customised (unique)
folder : add a folder to organize your projects (multiple) use folderBase= to place it in the tree
<pipeline uuid="Pipeline-Default" name="Pipeline-Default" folderBase="Base" jenkinsfile="jenkinsfile" repoGit="Test" branchFilter=".*"> : add a pipeline to build your project (multiple) repoGit= requires the name= part of a repoGit specified earlier
You will need to create slaves file in src/slaves.
If you're only using a single agent you can edit src/slaves/main.groovy with details from your agent's env.
If you have multiple agents, you should add new groovy files with each agent's env informations.
_Fedora_.groovytemplate for Linux based agents_OSX_.groovytemplate for MacOS based agents
Configuration details :
getName() : must return a string corresponding to <node> name from ci-example.xml
HOME : path to your agent's user home folder (not agent directory)
Tools4Dev_PATH : path to Tools4Dev installation
WS_ROOT : path to agent workdir (where it will execute jobs)
WORKSPACE : leave as defined, will get autogenerated at build time by system.jenkins.main.getWorkspace()
As root with this project loaded in a console, use command wks sync. This will create projects folders, job folders and agent nodes with correct file permissions.
If you need to recreate a job, delete the corresponding directory in JENKINS_ROOT/jobs and execute wks sync command.
You can refer yourself to this Tools4Jenkins PR to get a full example of all files to add/edit for a new project.