2021-01-29 00:20:46 +05:30
---
2022-11-25 23:54:43 +05:30
stage: Manage
2021-10-27 15:23:28 +05:30
group: Integrations
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2022-03-02 08:16:31 +05:30
# Jenkins integration **(FREE)**
2019-07-31 22:56:46 +05:30
2021-03-11 19:13:27 +05:30
> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 13.7.
2020-05-24 23:13:21 +05:30
2022-03-02 08:16:31 +05:30
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.
2020-05-24 23:13:21 +05:30
2022-03-02 08:16:31 +05:30
< i class = "fa fa-youtube-play youtube" aria-hidden = "true" > < / i >
For an overview of the Jenkins integration for GitLab, see
[GitLab workflow with Jira issues and Jenkins pipelines ](https://youtu.be/Jn-_fyra7xQ ).
2020-05-24 23:13:21 +05:30
2022-03-02 08:16:31 +05:30
Use the Jenkins integration when:
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
- You plan to migrate your CI from Jenkins to [GitLab CI/CD ](../ci/index.md )
in the future, but need an interim solution.
- You're invested in [Jenkins plugins ](https://plugins.jenkins.io/ ) and choose
to keep using Jenkins to build your apps.
2021-02-22 17:27:13 +05:30
NOTE:
2022-03-02 08:16:31 +05:30
This documentation focuses only on how to configure a Jenkins *integration* with
2021-04-17 20:07:23 +05:30
GitLab. Learn how to set up Jenkins [on your local machine ](../development/integrations/jenkins.md )
2022-03-02 08:16:31 +05:30
in the developer documentation, and how to migrate from Jenkins to GitLab CI/CD in the
2021-02-22 17:27:13 +05:30
[Migrating from Jenkins ](../ci/migration/jenkins.md ) documentation.
2019-10-12 21:52:04 +05:30
2022-03-02 08:16:31 +05:30
The Jenkins integration requires configuration in both GitLab and Jenkins.
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
## Grant Jenkins access to the GitLab project
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
Grant a GitLab user access to the relevant GitLab projects.
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
1. Create a new GitLab user, or choose an existing GitLab user.
2019-07-31 22:56:46 +05:30
2021-02-22 17:27:13 +05:30
This account is used by Jenkins to access the GitLab projects. We recommend creating a GitLab
2020-05-24 23:13:21 +05:30
user for only this purpose. If you use a person's account, and their account is deactivated or
2022-03-02 08:16:31 +05:30
deleted, the Jenkins integration stops working.
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
1. Grant the user permission to the GitLab projects.
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
If you're integrating Jenkins with many GitLab projects, consider granting the
2022-04-04 11:22:00 +05:30
user administrator access. Otherwise, add the user to each project
2022-05-07 20:08:51 +05:30
and grant the Maintainer role.
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
## Grant Jenkins access to the GitLab API
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
Create a personal access token to authorize Jenkins to access GitLab.
2019-07-31 22:56:46 +05:30
2021-03-11 19:13:27 +05:30
1. Sign in to GitLab as the user to be used with Jenkins.
2022-03-02 08:16:31 +05:30
1. On the top bar, in the top right corner, select your avatar.
2021-03-11 19:13:27 +05:30
1. Select **Edit profile** .
2021-11-11 11:23:49 +05:30
1. On the left sidebar, select **Access Tokens** .
2022-03-02 08:16:31 +05:30
1. Create a [personal access token ](../user/profile/personal_access_tokens.md ) and
select the **API** scope.
1. Copy the personal access token. You need it to [configure the Jenkins server ](#configure-the-jenkins-server ).
2020-05-24 23:13:21 +05:30
## Configure the Jenkins server
2019-07-31 22:56:46 +05:30
2021-02-22 17:27:13 +05:30
Install and configure the Jenkins plugin. The plugin must be installed and configured to
2020-05-24 23:13:21 +05:30
authorize the connection to GitLab.
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
1. On the Jenkins server, select **Manage Jenkins > Manage Plugins** .
2020-05-24 23:13:21 +05:30
1. Install the [Jenkins GitLab Plugin ](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin ).
2022-03-02 08:16:31 +05:30
1. Select **Manage Jenkins > Configure System** .
1. In the **GitLab** section, select **Enable authentication for '/project' end-point** .
1. Select **Add** , then choose **Jenkins Credential Provider** .
1. Select **GitLab API token** as the token type.
1. Enter the GitLab personal access token's value in **API Token** and select **Add** .
1. Enter the GitLab server's URL in **GitLab host URL** .
1. To test the connection, select **Test Connection** .
2020-05-24 23:13:21 +05:30
2022-03-02 08:16:31 +05:30
![Jenkins plugin configuration ](img/jenkins_gitlab_plugin_config.png )
For more information, see
[Jenkins-to-GitLab authentication ](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication ).
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
## Configure the Jenkins project
2021-02-22 17:27:13 +05:30
Set up the Jenkins project you intend to run your build on.
2020-05-24 23:13:21 +05:30
1. On your Jenkins instance, go to **New Item** .
1. Enter the project's name.
2022-03-02 08:16:31 +05:30
1. 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.
1. Choose your GitLab connection from the dropdown list.
1. Select **Build when a change is pushed to GitLab** .
1. Select the following checkboxes:
2020-05-24 23:13:21 +05:30
- **Accepted Merge Request Events**
- **Closed Merge Request Events**
2022-03-02 08:16:31 +05:30
1. Specify how the build status is reported to GitLab:
2020-05-24 23:13:21 +05:30
- 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:
```groovy
pipeline {
agent any
stages {
stage('gitlab') {
steps {
echo 'Notify GitLab'
updateGitlabCommitStatus name: 'build', state: 'pending'
updateGitlabCommitStatus name: 'build', state: 'success'
}
}
}
}
```
2021-09-30 23:02:18 +05:30
For more Jenkins Pipeline script examples, go to the [Jenkins GitLab plugin repository on GitHub ](https://github.com/jenkinsci/gitlab-plugin#scripted-pipeline-jobs ).
2020-05-24 23:13:21 +05:30
## Configure the GitLab project
2021-04-17 20:07:23 +05:30
Configure the GitLab integration with Jenkins in one of the following ways.
2020-05-24 23:13:21 +05:30
2022-03-02 08:16:31 +05:30
### Configure a Jenkins integration (recommended)
2021-04-17 20:07:23 +05:30
2021-09-30 23:02:18 +05:30
GitLab recommends this approach for Jenkins integrations because it is easier to configure
2022-03-02 08:16:31 +05:30
than the [webhook integration ](#configure-a-webhook ).
2021-02-22 17:27:13 +05:30
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2022-03-02 08:16:31 +05:30
1. On the left sidebar, select **Settings > Integrations** .
1. Select **Jenkins** .
1. Select the **Active** checkbox.
2020-05-24 23:13:21 +05:30
1. Select the events you want GitLab to trigger a Jenkins build for:
- Push
- Merge request
- Tag push
2022-03-02 08:16:31 +05:30
1. Enter the **Jenkins server URL** .
2022-07-16 23:28:13 +05:30
1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification ](../user/project/integrations/index.md#manage-ssl-verification ).
2020-05-24 23:13:21 +05:30
1. 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.
2022-03-02 08:16:31 +05:30
1. If your Jenkins server requires
authentication, enter the **Username** and **Password** .
1. To test the connection to Jenkins, select **Test settings** .
1. Select **Save changes** .
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
### Configure a webhook
2021-02-22 17:27:13 +05:30
If you are unable to provide GitLab with your Jenkins server login, you can use this option
to integrate GitLab and Jenkins.
2022-03-02 08:16:31 +05:30
1. In the configuration of your Jenkins job, in the GitLab configuration section, select **Advanced** .
1. Under **Secret Token** , select **Generate** .
1. Copy the token, and save the job configuration.
2021-04-17 20:07:23 +05:30
1. In GitLab, create a webhook for your project, enter the trigger URL
2022-03-02 08:16:31 +05:30
(such as `https://JENKINS_URL/project/YOUR_JOB` ) and paste the token in **Secret Token** .
1. To test the webhook, select **Test** .
## Related topics
- For a real use case, read the blog post
[Continuous integration: From Jenkins to GitLab using Docker ](https://about.gitlab.com/blog/2017/07/27/docker-my-precious/ ).
- See the ['GitLab vs. Jenkins' comparison page ](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab/ )
for information on how moving to a single application for the entire software development
lifecycle can decrease hours spent on maintaining toolchains by 10% or more.
2021-02-22 17:27:13 +05:30
2019-07-31 22:56:46 +05:30
## Troubleshooting
2022-01-26 12:08:38 +05:30
### 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
2022-10-11 01:57:18 +05:30
[GitLab installation's allowlist ](../security/webhooks.md#create-an-allowlist-for-local-requests ).
2022-01-26 12:08:38 +05:30
- The credentials for the Jenkins instance do not have sufficient access or are invalid.
2022-07-23 23:45:48 +05:30
- The **Enable authentication for `/project` end-point** checkbox is not selected in your [Jenkin's plugin configuration ](#configure-the-jenkins-server ).
2022-01-26 12:08:38 +05:30
2019-07-31 22:56:46 +05:30
### Error in merge requests - "Could not connect to the CI server"
2022-03-02 08:16:31 +05:30
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 ](../api/commits.md#commit-status ).
This issue occurs when Jenkins is not properly
configured or there is an error reporting the status via the API.
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
To fix this issue, ensure you:
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
1. [Configure the Jenkins server ](#configure-the-jenkins-server ) for GitLab API access.
2020-05-24 23:13:21 +05:30
1. [Configure the Jenkins project ](#configure-the-jenkins-project ), including the
2019-09-30 21:07:59 +05:30
'Publish build status to GitLab' post-build action.
2020-01-01 13:55:28 +05:30
2022-03-02 08:16:31 +05:30
### Merge request event does not trigger a Jenkins pipeline
2020-01-01 13:55:28 +05:30
2022-03-02 08:16:31 +05:30
This issue can occur when the request exceeds the
[webhook timeout ](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered ),
which is set to 10 seconds by default.
2022-07-16 23:28:13 +05:30
Check the [service hook logs ](../user/project/integrations/index.md#troubleshooting-integrations )
2022-03-02 08:16:31 +05:30
for request failures or check the `/var/log/gitlab/gitlab-rails/production.log`
file for messages like:
2020-01-01 13:55:28 +05:30
```plaintext
WebHook Error => Net::ReadTimeout
```
or
```plaintext
WebHook Error => execution expired
```
2022-03-02 08:16:31 +05:30
Or check for duplicate messages in `/var/log/gitlab/gitlab-rail` , like:
2020-01-01 13:55:28 +05:30
2020-04-22 19:07:51 +05:30
```plaintext
2020-01-01 13:55:28 +05:30
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
```
2021-09-30 23:02:18 +05:30
2022-11-25 23:54:43 +05:30
On self-managed GitLab instances, you can fix this issue by [increasing the webhook timeout value ](../administration/instance_limits.md#webhook-timeout ).
2022-03-02 08:16:31 +05:30
2021-09-30 23:02:18 +05:30
### Enable job logs in Jenkins
2022-03-02 08:16:31 +05:30
To troubleshoot an integration issue, you can enable job logs in Jenkins to get
more details about your builds.
2021-09-30 23:02:18 +05:30
To enable job logs in Jenkins:
1. Go to **Dashboard > Manage Jenkins > System Log** .
1. Select **Add new log recorder** .
1. Enter a name for the log recorder.
2022-05-07 20:08:51 +05:30
1. On the next screen, select **Add** and enter `com.dabsquared.gitlabjenkins` .
2021-09-30 23:02:18 +05:30
1. Make sure that the Log Level is **All** and select **Save** .
2022-03-02 08:16:31 +05:30
To view your logs:
1. Run a build.
1. Go to **Dashboard > Manage Jenkins > System Log** .
1. Select your logger and check the logs.