diff options
Diffstat (limited to 'doc/integration/jenkins.md')
| -rw-r--r-- | doc/integration/jenkins.md | 58 |
1 files changed, 37 insertions, 21 deletions
diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7eb147c1fe6..7be2a6efd71 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,23 +1,21 @@ --- -stage: none -group: unassigned -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/#designated-technical-writers +stage: Create +group: Ecosystem +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 **(STARTER)** +# Jenkins CI service **(CORE)** -NOTE: **Note:** -This documentation focuses only on how to **configure** a Jenkins *integration* with -GitLab. Learn how to **migrate** from Jenkins to GitLab CI/CD in our -[Migrating from Jenkins](../ci/migration/jenkins.md) documentation. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to Core in GitLab 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 GitLab's Jenkins integration, watch the following video: +To better understand the GitLab Jenkins integration, watch the following video: - [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) + Use the Jenkins integration with GitLab when: - You plan to migrate your CI from Jenkins to [GitLab CI/CD](../ci/README.md) in the future, but @@ -29,11 +27,16 @@ For a real use case, read the blog post [Continuous integration: From Jenkins to 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.html). +the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab/). + +NOTE: +This documentation focuses only on how to **configure** a Jenkins *integration* with +GitLab. Learn how to **migrate** from Jenkins to GitLab CI/CD in our +[Migrating from Jenkins](../ci/migration/jenkins.md) documentation. ## Configure GitLab integration with Jenkins -GitLab's Jenkins integration requires installation and configuration in both GitLab and 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. @@ -54,9 +57,9 @@ Grant a GitLab user access to the select GitLab projects. 1. Create a new GitLab user, or choose an existing GitLab user. - This account will be used by Jenkins to access the GitLab projects. We recommend creating a GitLab + 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 will stop working. + deleted, the GitLab-Jenkins integration stops working. 1. Grant the user permission to the GitLab projects. @@ -72,11 +75,11 @@ Create a personal access token to authorize Jenkins' access to GitLab. 1. Click **Access Tokens** in the sidebar. 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). +1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server) section. ## Configure the Jenkins server -Install and configure the Jenkins plugins. Both plugins must be installed and configured to +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**. @@ -96,12 +99,12 @@ For more information, see GitLab Plugin documentation about ## Configure the Jenkins project -Set up the Jenkins project you’re going to run your build on. +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 will update the build status on + 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. @@ -136,6 +139,8 @@ Set up the Jenkins project you’re going to run your build on. Configure the GitLab integration with Jenkins. +### Option 1: Jenkins integration (recommended) + 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. @@ -153,6 +158,17 @@ Configure the GitLab integration with Jenkins. authentication. 1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. +### Option 2: 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 GitLab, create a webhook for your project, enter the trigger URL (e.g. `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. + ## Troubleshooting ### Error in merge requests - "Could not connect to the CI server" @@ -183,14 +199,14 @@ WebHook Error => execution expired ``` If those are present, the request is exceeding the -[webhook timeout](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event), +[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 will need to be increased -in the `gitlab.rb` config file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). +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`), this -could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event): +could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start |