Jenkins integration (FREE)

Moved to GitLab Free in 13.7.

You can trigger a build in Jenkins when you push code to your repository or create a merge request in GitLab. The Jenkins pipeline status displays on merge requests widgets and on the GitLab project's home page.

For an overview of the Jenkins integration for GitLab, see GitLab workflow with Jira issues and Jenkins pipelines.

Use the Jenkins integration when:

You plan to migrate your CI from Jenkins to GitLab CI/CD in the future, but need an interim solution.
You're invested in Jenkins plugins and choose to keep using Jenkins to build your apps.

NOTE: This documentation focuses only on how to configure a Jenkins integration with GitLab. Learn how to set up Jenkins on your local machine in the developer documentation, and how to migrate from Jenkins to GitLab CI/CD in the Migrating from Jenkins documentation.

The Jenkins integration requires configuration in both GitLab and Jenkins.

Grant Jenkins access to the GitLab project

Grant a GitLab user access to the relevant GitLab projects.

Create a new GitLab user, or choose an existing GitLab user.

This account is used by Jenkins to access the GitLab projects. We recommend creating a GitLab user for only this purpose. If you use a person's account, and their account is deactivated or deleted, the Jenkins integration stops working.
Grant the user permission to the GitLab projects.

If you're integrating Jenkins with many GitLab projects, consider granting the user administrator access. Otherwise, add the user to each project and grant the Maintainer role.

Grant Jenkins access to the GitLab API

Create a personal access token to authorize Jenkins to access GitLab.

Sign in to GitLab as the user to be used with Jenkins.
On the top bar, in the top right corner, select your avatar.
Select Edit profile.
On the left sidebar, select Access Tokens.
Create a personal access token and select the API scope.
Copy the personal access token. You need it to configure the Jenkins server.

Configure the Jenkins server

Install and configure the Jenkins plugin. The plugin must be installed and configured to authorize the connection to GitLab.

On the Jenkins server, select Manage Jenkins > Manage Plugins.
Install the Jenkins GitLab Plugin.
Select Manage Jenkins > Configure System.
In the GitLab section, select Enable authentication for '/project' end-point.
Select Add, then choose Jenkins Credential Provider.
Select GitLab API token as the token type.
Enter the GitLab personal access token's value in API Token and select Add.
Enter the GitLab server's URL in GitLab host URL.
To test the connection, select Test Connection.

For more information, see Jenkins-to-GitLab authentication.

Configure the Jenkins project

Set up the Jenkins project you intend to run your build on.

On your Jenkins instance, go to New Item.
Enter the project's name.
Select Freestyle or Pipeline and select OK. We recommend a Freestyle project, because the Jenkins plugin updates the build status on GitLab. In a Pipeline project, you must configure a script to update the status on GitLab.
Choose your GitLab connection from the dropdown list.
Select Build when a change is pushed to GitLab.
Select the following checkboxes:
- Accepted Merge Request Events
- Closed Merge Request Events
Specify how the build status is reported to GitLab:
- If you created a Freestyle project, in the Post-build Actions section, choose Publish build status to GitLab.
- If you created a Pipeline project, you must use a Jenkins Pipeline script to update the status on GitLab.
  
  Example Jenkins Pipeline script:
```
pipeline {
   agent any

   stages {
      stage('gitlab') {
         steps {
            echo 'Notify GitLab'
            updateGitlabCommitStatus name: 'build', state: 'pending'
            updateGitlabCommitStatus name: 'build', state: 'success'
         }
      }
   }
}
```
  For more Jenkins Pipeline script examples, go to the Jenkins GitLab plugin repository on GitHub.

Configure the GitLab project

Configure the GitLab integration with Jenkins in one of the following ways.

Configure a Jenkins integration (recommended)

GitLab recommends this approach for Jenkins integrations because it is easier to configure than the webhook integration.

On the top bar, select Menu > Projects and find your project.
On the left sidebar, select Settings > Integrations.
Select Jenkins.
Select the Active checkbox.
Select the events you want GitLab to trigger a Jenkins build for:
- Push
- Merge request
- Tag push
Enter the Jenkins server URL.
Optional. Clear the Enable SSL verification checkbox to disable SSL verification.
Enter the Project name.

The project name should be URL-friendly, where spaces are replaced with underscores. To ensure the project name is valid, copy it from your browser's address bar while viewing the Jenkins project.
If your Jenkins server requires authentication, enter the Username and Password.
To test the connection to Jenkins, select Test settings.
Select Save changes.

Configure a webhook

If you are unable to provide GitLab with your Jenkins server login, you can use this option to integrate GitLab and Jenkins.

In the configuration of your Jenkins job, in the GitLab configuration section, select Advanced.
Under Secret Token, select Generate.
Copy the token, and save the job configuration.
In GitLab, create a webhook for your project, enter the trigger URL (such as https://JENKINS_URL/project/YOUR_JOB) and paste the token in Secret Token.
To test the webhook, select Test.

Troubleshooting

Error during GitLab configuration - "Connection failed. Please check your settings"

If you get this error message while configuring GitLab, the following are possible causes:

GitLab is unable to reach your Jenkins instance at the address. If your GitLab instance is self-managed, try pinging the Jenkins instance at the domain provided on the GitLab instance.
The Jenkins instance is at a local address and is not included in the GitLab installation's allowlist.
The credentials for the Jenkins instance do not have sufficient access or are invalid.
The Enable authentication for /project end-point checkbox is not selected in your Jenkin's plugin configuration.

Error in merge requests - "Could not connect to the CI server"

You might get the Could not connect to the CI server error if GitLab did not receive a build status update from Jenkins via the Commit Status API.

This issue occurs when Jenkins is not properly configured or there is an error reporting the status via the API.

To fix this issue, ensure you:

Configure the Jenkins server for GitLab API access.
Configure the Jenkins project, including the 'Publish build status to GitLab' post-build action.

Merge request event does not trigger a Jenkins pipeline

This issue can occur when the request exceeds the webhook timeout, which is set to 10 seconds by default.

Check the service hook logs for request failures or check the /var/log/gitlab/gitlab-rails/production.log file for messages like:

WebHook Error => Net::ReadTimeout

WebHook Error => execution expired

Or check for duplicate messages in /var/log/gitlab/gitlab-rail, like:

2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start
2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start

To fix this issue:

Increase the gitlab_rails['webhook_timeout'] value in the gitlab.rb configuration file.
Restart GitLab:
```
gitlab-ctl reconfigure
```

Enable job logs in Jenkins

To troubleshoot an integration issue, you can enable job logs in Jenkins to get more details about your builds.

To enable job logs in Jenkins:

Go to Dashboard > Manage Jenkins > System Log.
Select Add new log recorder.
Enter a name for the log recorder.
On the next screen, select Add and enter com.dabsquared.gitlabjenkins.
Make sure that the Log Level is All and select Save.

To view your logs:

Run a build.
Go to Dashboard > Manage Jenkins > System Log.
Select your logger and check the logs.