Tuleap provides Continuous Integration to teams via a deep integration with Jenkins.
Tuleap team recommends to avoid big Jenkins instances shared by many projects and many teams as the security model of Jenkins doesn’t allow to have a strict split of areas. That is to say, to guaranty that 2 concurrent teams that share the same Jenkins sever cannot have access to the code of each other.
In case of doubt the strategy of “One Tuleap Project, one Jenkins Master” is safe and efficient.
This section will cover how to configure a Jenkins server to be used efficiently with Tuleap. We assume a fresh Jenkins instance that was just installed.
Some adaptations might be needed if you modify an existing Jenkins server (be very careful with authentication to not lock yourself out of Jenkins).
Both Jenkins and Tuleap servers must be in https and certificate must be either valid or, at least, trusted.
If you cannot have valid certificates:
Two plugins should be installed:
Both are available publicly on the Jenkins plugin marketplace and the installation is done from within Jenkins in “Manage Plugins” section.
You might also need to install other plugins related to your pipeline of email notifications, artifact publishing to Artifactory, etc. This is business specific to each project and not covered in this documentation.
First, you need to associate your Jenkins server with a Tuleap server. This is done in “Manage Jenkins > System configuration”.
If the connection to the Tuleap server is successful you will see
Connexion established with these Urls message in
the Jenkins interface (as in the previous screenshot). Otherwise you will get a stacktrace (Jenkins…) with, hopefully,
an error message that will help to diagnose the problem.
Most common issues are related to DNS (is your server name valid and can Jenkins access it) and TLS (does jenkins trust Tuleap server).
This section requires that your Tuleap server has OAuth2 Server plugin installed.
First, on your Tuleap server, in one of your project, you need to create a new OAuth2 app.
The app will ask for a callback URL. This callback URL is your Jenkins server base URL (eg. https://jenkins.example.com/jenkins) +
The plugin allows the PKCE usage for the authentication. You can force its usage at the creation of the OAuth2 app.
Keep the generated Client Secret securely until the next step.
Then Jenkins, go In Manage Jenkins > Configure Global Security, and select Tuleap Authentication and fill:
With the values provided by Tuleap.
Ensure that Authorization (bellow Authentication section) is still set to Anyone can do anything and click save.
You should then be able to login on Jenkins with you Tuleap credentials and still have access to Manage Jenkins.
If you locked yourself out of Jenkins you can start over by disabling security.
Tuleap Git / Jenkins integration¶
Thanks to Tuleap Git Branch Source Jenkins plugin, most of the integration between the two tools is completely streamlined.
The configuration is done once at project level, then every new git repository created in Tuleap will be automatically
discovered by Jenkins, branches will be inspected to find
Jenkinsfile and created corresponding pipelines.
Whenever a new commit will be pushed, the corresponding job will be triggered on Jenkins.
Step 1: Have an access key to your repositories¶
In Tuleap, either with a service or personal account that have read access to the project’s repositories go in user preferences,
“Keys & Tokens” section and generate a new Access Key with both
Step 2: Create a Tuleap Project¶
In Jenkins, create a new job with type “Tuleap Project”. It should be named after your Tuleap project name to ease organisation.
Once the job created you should grant it access to Tuleap with the credential you generated at Step 1. Near the credential drop down, you have a “Add” button. Create a new “Project name” credential of type “Tuleap Access Key” and give it a descriptive id so you can find it later.
Once the credential is saved, select it in the “Credentials” dropdown.
In the “Project” dropdown right after, select the Tuleap project you want to automate.
You can adjust “Behaviours” to match your need. By default we suggest to remove
Exclude field of “Filter by name (with wildcards)” section
otherwise nothing will be built at all.
When the configuration is ready, save it. This will trigger a scan of your project to look for git repositories, their branches
Jenkinsfile to create Jenkins jobs.
When the scan is completed, you will find all the git repositories where Jenkins found a
Jenkinsfile and the status
of the builds that were triggered.
On Jenkins, in your project settings, you might also want to adjust “Scan Project Triggers” to a shorter period otherwise you will have to wait for 1 day between a new repository creation and jenkins to discover it.
As this will trigger a full analyze of all branches of git repositories of your Tuleap project, you need to find a balance between reactivity and Tuleap server overloading.
If you don’t create a new repository every other hours, you might want to let 1 day period and trigger manually the scan whenever you create a new repository.
Step 3: Tell Tuleap where the Jenkins server is¶
The final step is on Tuleap. You need to inform the git server where is the Jenkins server that must be informed about new commits that are pushed.
In the administration of the Git service of your project, there is a
Jenkins tab where you set the Jenkins root url.
When those 3 steps are completed, you no longer have to worry about Jenkins / Tuleap integration, everything is automated.
Continuous Integration service in Tuleap¶
The “Continuous Integration” service in Tuleap refers to an historical implementation that was mainly targeting Subversion and CVS.
It also provides some widgets that can be used on Project and Personal dashboards.
Reference Jenkins job with your Tuleap project¶
In order to link Jenkins job with your project, select the Continuous Integration tab of
your project, and then select the ‘Add a job’ link. You need then to
give the URL of the Hudson job you want to associate with your project
You may also want to enable the auto trigger of the build for this job after each commit in your project repository (CVS or Subversion). If you have protected your build with a token, you can specify this token.
By checking this option, each commit will trigger a build of the associated job, using the pre-commit hook (you don’t have anything more to do).
By the way, it is possible to link several Jenkins jobs with one Tuleap project.
Jenkins jobs and builds¶
When you select the Continuous Integration tab of your project, you can see a table with all the jobs associated with your project. For every job, you can see the current status (colored bullet left to the name of the job), the name, the last successful build, the last failed build, if you have enabled SCM trigger or not.
Project admins will also see for each job some icons that let them modify the job or delete it (remove the link with Tuleap).
The name of the job is automatically detected during job creation. But you can change it if needed. This is pretty convenient if you want to make references to Jenkins items (see Make a reference to a Job). Spaces in the name of jobs are not allowed. They are replaced by (_), in order to allow references.
It is possible to make references to Jenkins items in Tuleap. There are some predefined references (job, build), but you can also create your own references if needed (see Reference Overview for more details about references)
Make a reference to a Job¶
The keyword to make a reference to a Job is: job. To make a reference to a job, you can use the expressions:
job #JobNameToReference (the job must be in the current project)
job #project:JobNameToReference (will make a reference to the job ‘JobNameToReference’ of the project ‘project’)
job #project_num:JobNameToReference (will make a reference to the job ‘JobNameToReference’ of the project with number ‘project_num’)
Make a reference to a build¶
The keyword to make a reference to a build is: build. To make a reference to a build, you can use the expressions:
build #XXX (there must be only one job associated with the current project, and the referenced build will be the build number ‘XXX’ of this job)
build #AJob/XXX (will make a reference to build number ‘XXX’ of job named ‘AJob’ of the current project)
build #project:AJob/XXX (will make a reference to the build number ‘XXX’ of the job ‘AJob’ of project ‘project’)
build #projet_num:AJob/XXX (will make a reference to the build number ‘XXX’ of the job ‘AJob’ of the project number ‘project_num’)