debian-mirror-gitlab/doc/integration/jenkins.md

stage	group	info
Ecosystem	Integrations	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Jenkins CI service (FREE)

Moved to GitLab Free in 13.7.

From GitLab, you can trigger a Jenkins build when you push code to a repository, or when a merge request is created. In return, the Jenkins pipeline status is shown on merge requests widgets and on the GitLab project's home page.

To better understand the GitLab Jenkins integration, watch the following video:

• GitLab workflow with Jira issues and Jenkins pipelines

Use the Jenkins integration with GitLab 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.

For a real use case, read the blog post Continuous integration: From Jenkins to GitLab using Docker.

Moving from a traditional CI plug-in to a single application for the entire software development life cycle can decrease hours spent on maintaining toolchains by 10% or more. For more details, see the 'GitLab vs. Jenkins' comparison page.

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 our developer documentation, and how to migrate from Jenkins to GitLab CI/CD in our Migrating from Jenkins documentation.

Configure GitLab integration with Jenkins

The GitLab Jenkins integration requires installation and configuration in both GitLab and Jenkins. In GitLab, you need to grant Jenkins access to the relevant projects. In Jenkins, you need to install and configure several plugins.

GitLab requirements

• Grant Jenkins permission to GitLab project
• Configure GitLab API access
• Configure the GitLab project

Jenkins requirements

• Configure the Jenkins server
• Configure the Jenkins project

Grant Jenkins access to GitLab project

Grant a GitLab user access to the select GitLab projects.

1. 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 GitLab-Jenkins integration stops working.

2. Grant the user permission to the GitLab projects.

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

Configure GitLab API access

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

1. Sign in to GitLab as the user to be used with Jenkins.
2. In the top-right corner, select your avatar.
3. Select Edit profile.
4. On the left sidebar, select Access Tokens.
5. Create a personal access token with the API scope checkbox checked. For more details, see Personal access tokens.
6. Record the personal access token's value, because it's required in Configure the Jenkins server section.

Configure the Jenkins server

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

1. On the Jenkins server, go to Manage Jenkins > Manage Plugins.
2. Install the Jenkins GitLab Plugin.
3. Go to Manage Jenkins > Configure System.
4. In the GitLab section, check the Enable authentication for '/project' end-point checkbox.
5. Click Add, then choose Jenkins Credential Provider.
6. Choose GitLab API token as the token type.
7. Enter the GitLab personal access token's value in the API Token field and click Add.
8. Enter the GitLab server's URL in the GitLab host URL field.
9. Click Test Connection, ensuring the connection is successful before proceeding.

For more information, see GitLab Plugin documentation about Jenkins-to-GitLab authentication.

Configure the Jenkins project

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

1. On your Jenkins instance, go to New Item.
2. Enter the project's name.
3. Choose between Freestyle or Pipeline and click 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.
4. Choose your GitLab connection from the dropdown.
5. Check the Build when a change is pushed to GitLab checkbox.
6. Check the following checkboxes:
   • Accepted Merge Request Events
   • Closed Merge Request Events
7. Specify how 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.

Recommended Jenkins integration

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

1. Create a new GitLab project or choose an existing one.

2. Go to Settings > Integrations, then select Jenkins CI.

3. Turn on the Active toggle.

4. Select the events you want GitLab to trigger a Jenkins build for:

   • Push
   • Merge request
   • Tag push

5. Enter the Jenkins URL.

6. 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.

7. Enter the Username and Password if your Jenkins server requires authentication.

8. Click Test settings and save changes. GitLab tests the connection to Jenkins.

Webhook integration

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

1. In the configuration of your Jenkins job, in the GitLab configuration section, click Advanced.
2. Click the Generate button under the Secret Token field.
3. Copy the resulting token, and save the job configuration.
4. 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 the Secret Token field.
5. After you add the webhook, click the Test button, and it should succeed.

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"

This integration relies on Jenkins reporting the build status back to GitLab via the Commit Status API.

The error 'Could not connect to the CI server' usually means that GitLab did not receive a build status update via the API. Either Jenkins was not properly configured or there was an error reporting the status via the API.

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

Merge Request event does not trigger a Jenkins Pipeline

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

WebHook Error => Net::ReadTimeout

or

WebHook Error => execution expired

If those are present, the request is exceeding the webhook timeout, which is set to 10 seconds by default.

To fix this the gitlab_rails['webhook_timeout'] value must be increased in the gitlab.rb configuration file, followed by the gitlab-ctl reconfigure command.

If you don't find the errors above, but do find duplicate entries like below (in /var/log/gitlab/gitlab-rail), webhook requests may be timing out:

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

Enable job logs in Jenkins

When troubleshooting an integration issue, it is useful to enable job logs in Jenkins to see more details about what is happening under the hood. To enable job logs in Jenkins:

1. Go to Dashboard > Manage Jenkins > System Log.
2. Select Add new log recorder.
3. Enter a name for the log recorder.
4. On the next screen, select Add and enter org.jenkinsci.plugins.workflow.job in the text field.
5. Make sure that the Log Level is All and select Save.

Now, after you run a build, you can go to the loggers page (Dashboard > Manage Jenkins > System Log), select your logger, and check the logs.