252 lines
10 KiB
Markdown
252 lines
10 KiB
Markdown
---
|
||
stage: Ecosystem
|
||
group: Integrations
|
||
info: 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 integration **(FREE)**
|
||
|
||
> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) 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.
|
||
|
||
<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).
|
||
|
||
Use the Jenkins integration when:
|
||
|
||
- 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.
|
||
|
||
NOTE:
|
||
This documentation focuses only on how to configure a Jenkins *integration* with
|
||
GitLab. Learn how to set up Jenkins [on your local machine](../development/integrations/jenkins.md)
|
||
in the developer documentation, and how to migrate from Jenkins to GitLab CI/CD in the
|
||
[Migrating from Jenkins](../ci/migration/jenkins.md) 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.
|
||
|
||
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 Jenkins integration stops working.
|
||
|
||
1. 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.
|
||
|
||
1. Sign in to GitLab as the user to be used with Jenkins.
|
||
1. On the top bar, in the top right corner, select your avatar.
|
||
1. Select **Edit profile**.
|
||
1. On the left sidebar, select **Access Tokens**.
|
||
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).
|
||
|
||
## 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, select **Manage Jenkins > Manage Plugins**.
|
||
1. Install the [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin).
|
||
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**.
|
||
|
||
|
||
|
||
For more information, see
|
||
[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#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**.
|
||
1. Enter the project's name.
|
||
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:
|
||
- **Accepted Merge Request Events**
|
||
- **Closed Merge Request Events**
|
||
1. 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:
|
||
|
||
```groovy
|
||
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](https://github.com/jenkinsci/gitlab-plugin#scripted-pipeline-jobs).
|
||
|
||
## 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](#configure-a-webhook).
|
||
|
||
1. On the top bar, select **Menu > Projects** and find your project.
|
||
1. On the left sidebar, select **Settings > Integrations**.
|
||
1. Select **Jenkins**.
|
||
1. Select the **Active** checkbox.
|
||
1. Select the events you want GitLab to trigger a Jenkins build for:
|
||
- Push
|
||
- Merge request
|
||
- Tag push
|
||
1. Enter the **Jenkins server URL**.
|
||
1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](../user/project/integrations/index.md#manage-ssl-verification).
|
||
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.
|
||
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**.
|
||
|
||
### 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.
|
||
|
||
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.
|
||
1. 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**.
|
||
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.
|
||
|
||
## 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](../security/webhooks.md#allowlist-for-local-requests).
|
||
- 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](#configure-the-jenkins-server).
|
||
|
||
### 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](../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.
|
||
|
||
To fix this issue, ensure you:
|
||
|
||
1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access.
|
||
1. [Configure the Jenkins project](#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](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered),
|
||
which is set to 10 seconds by default.
|
||
|
||
Check the [service hook logs](../user/project/integrations/index.md#troubleshooting-integrations)
|
||
for request failures or check the `/var/log/gitlab/gitlab-rails/production.log`
|
||
file for messages like:
|
||
|
||
```plaintext
|
||
WebHook Error => Net::ReadTimeout
|
||
```
|
||
|
||
or
|
||
|
||
```plaintext
|
||
WebHook Error => execution expired
|
||
```
|
||
|
||
Or check for duplicate messages in `/var/log/gitlab/gitlab-rail`, like:
|
||
|
||
```plaintext
|
||
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:
|
||
|
||
1. Increase the `gitlab_rails['webhook_timeout']` value in the `gitlab.rb`
|
||
configuration file.
|
||
1. [Restart](../administration/restart_gitlab.md) GitLab:
|
||
|
||
```shell
|
||
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:
|
||
|
||
1. Go to **Dashboard > Manage Jenkins > System Log**.
|
||
1. Select **Add new log recorder**.
|
||
1. Enter a name for the log recorder.
|
||
1. On the next screen, select **Add** and enter `com.dabsquared.gitlabjenkins`.
|
||
1. Make sure that the Log Level is **All** and select **Save**.
|
||
|
||
To view your logs:
|
||
|
||
1. Run a build.
|
||
1. Go to **Dashboard > Manage Jenkins > System Log**.
|
||
1. Select your logger and check the logs.
|