diff options
Diffstat (limited to 'doc/integration/jenkins.md')
| -rw-r--r-- | doc/integration/jenkins.md | 209 |
1 files changed, 107 insertions, 102 deletions
diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 822530775e5..bae52622966 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -4,100 +4,80 @@ 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 CI service **(FREE)** +# Jenkins integration **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) 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. +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. -To better understand the GitLab Jenkins integration, watch the following video: +<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). -- [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) +Use the Jenkins integration when: -Use the Jenkins integration with GitLab 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. - -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/). - -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](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab/). +- 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 +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 our developer documentation, and how to **migrate** from Jenkins to GitLab CI/CD in our +in the developer documentation, and how to migrate from Jenkins to GitLab CI/CD in the [Migrating from Jenkins](../ci/migration/jenkins.md) 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](#grant-jenkins-access-to-gitlab-project) -- [Configure GitLab API access](#configure-gitlab-api-access) -- [Configure the GitLab project](#configure-the-gitlab-project) - -### Jenkins requirements +The Jenkins integration requires configuration in both GitLab and Jenkins. -- [Configure the Jenkins server](#configure-the-jenkins-server) -- [Configure the Jenkins project](#configure-the-jenkins-project) +## Grant Jenkins access to the GitLab project -## Grant Jenkins access to GitLab project - -Grant a GitLab user access to the select GitLab projects. +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 GitLab-Jenkins integration stops working. + 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 the global - Administrator role. Otherwise, add the user to each project, and grant the Developer role. + If you're integrating Jenkins with many GitLab projects, consider granting the + user the administrator access level. Otherwise, add the user to each project + and grant the Developer role. -## Configure GitLab API access +## Grant Jenkins access to the GitLab API -Create a personal access token to authorize Jenkins' access to GitLab. +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. In the top-right corner, select your avatar. +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 with the **API** scope checkbox checked. For more details, see - [Personal access tokens](../user/profile/personal_access_tokens.md). -1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. +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, go to **Manage Jenkins > Manage Plugins**. +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. Go to **Manage Jenkins > Configure System**. -1. In the **GitLab** section, check the **Enable authentication for '/project' end-point** checkbox. -1. Click **Add**, then choose **Jenkins Credential Provider**. -1. Choose **GitLab API token** as the token type. -1. Enter the GitLab personal access token's value in the **API Token** field and click **Add**. -1. Enter the GitLab server's URL in the **GitLab host URL** field. -1. Click **Test Connection**, ensuring the connection is successful before proceeding. - -For more information, see GitLab Plugin documentation about -[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication). +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 @@ -105,15 +85,15 @@ 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. 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. -1. Choose your GitLab connection from the dropdown. -1. Check the **Build when a change is pushed to GitLab** checkbox. -1. Check the following checkboxes: +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 build status is reported to GitLab: +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 @@ -143,39 +123,49 @@ Set up the Jenkins project you intend to run your build on. Configure the GitLab integration with Jenkins in one of the following ways. -### Recommended Jenkins integration +### Configure a Jenkins integration (recommended) GitLab recommends this approach for Jenkins integrations because it is easier to configure -than the [webhook integration](#webhook-integration). +than the [webhook integration](#configure-a-webhook). -1. Create a new GitLab project or choose an existing one. -1. Go to **Settings > Integrations**, then select **Jenkins CI**. -1. Turn on the **Active** toggle. +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 URL**. +1. Enter the **Jenkins server URL**. 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. Enter the **Username** and **Password** if your Jenkins server requires - authentication. -1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. +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**. -### Webhook integration +### 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, click **Advanced**. -1. Click the **Generate** button under the **Secret Token** field. -1. Copy the resulting token, and save the job configuration. +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 the **Secret Token** field. -1. After you add the webhook, click the **Test** button, and it should succeed. + (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 @@ -188,24 +178,31 @@ If you get this error message while configuring GitLab, the following are possib - 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). +- 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" -This integration relies on Jenkins reporting the build status back to GitLab via -the [Commit Status API](../api/commits.md#commit-status). +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. -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. +To fix this issue, ensure you: -1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access +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 +### Merge request event does not trigger a Jenkins pipeline -Check [service hook logs](../user/project/integrations/overview.md#troubleshooting-integrations) for request failures or check the `/var/log/gitlab/gitlab-rails/production.log` file for messages like: +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/overview.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 @@ -217,30 +214,38 @@ or WebHook Error => execution expired ``` -If those are present, the request is exceeding the -[webhook timeout](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered), -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](../administration/restart_gitlab.md). - -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](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): +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 -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 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 `org.jenkinsci.plugins.workflow.job` in the text field. +1. On the next screen, select **Add** and enter `org.jenkinsci.plugins.workflow.job`. 1. 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. +To view your logs: + +1. Run a build. +1. Go to **Dashboard > Manage Jenkins > System Log**. +1. Select your logger and check the logs. |