diff options
Diffstat (limited to 'doc/integration/jenkins.md')
| -rw-r--r-- | doc/integration/jenkins.md | 125 |
1 files changed, 65 insertions, 60 deletions
diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 736f5bc080c..4f76301adeb 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -8,33 +8,34 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [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. +[Jenkins](https://www.jenkins.io/) is an open source automation server that supports +building, deploying and automating projects. -<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 should use a 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. -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. +After you have configured a Jenkins integration, you 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 request widgets and 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). + +To configure a Jenkins integration with GitLab: -The Jenkins integration requires configuration in both GitLab and Jenkins. +- Grant Jenkins access to the GitLab project. +- Configure the Jenkins server. +- Configure the Jenkins project. +- Configure the GitLab project. ## Grant Jenkins access to the GitLab project -To grant Jenkins access to the GitLab project: - 1. Create a personal, project, or group access token. - [Create a personal access token](../user/profile/personal_access_tokens.md#create-a-personal-access-token) @@ -46,20 +47,22 @@ To grant Jenkins access to the GitLab project: to use the token for all Jenkins integrations in all projects of that group. 1. Set the access token scope to **API**. -1. Copy the access token value to [configure the Jenkins server](#configure-the-jenkins-server). +1. Copy the access token value to 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. +Install and configure the Jenkins plugin 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 the **Available** tab. Search for `gitlab-plugin` and select it to install. + See the [Jenkins GitLab documentation](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin) + for other ways to install the 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. In **API Token**, [paste the value you copied from GitLab](#grant-jenkins-access-to-the-gitlab-project) and select **Add**. +1. In **API Token**, [paste the access token value you copied from GitLab](#grant-jenkins-access-to-the-gitlab-project) + and select **Add**. 1. Enter the GitLab server's URL in **GitLab host URL**. 1. To test the connection, select **Test Connection**. @@ -72,21 +75,21 @@ For more information, see Set up the Jenkins project you intend to run your build on. -1. On your Jenkins instance, go to **New Item**. +1. On your Jenkins instance, select **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. + You should select 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. + - 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: @@ -106,18 +109,19 @@ Set up the Jenkins project you intend to run your build on. } ``` - For more Jenkins Pipeline script examples, go to the [Jenkins GitLab plugin repository on GitHub](https://github.com/jenkinsci/gitlab-plugin#scripted-pipeline-jobs). + For more Jenkins Pipeline script examples, see 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) +### With a Jenkins server URL -GitLab recommends this approach for Jenkins integrations because it is easier to configure -than the [webhook integration](#configure-a-webhook). +You should use this approach for Jenkins integrations if you can provide GitLab +with your Jenkins server URL and authentication information. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. 1. Select **Jenkins**. 1. Select the **Active** checkbox. @@ -128,61 +132,62 @@ than the [webhook integration](#configure-a-webhook). 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. If your Jenkins server requires authentication, enter the **Username** and **Password**. 1. Optional. Select **Test settings**. 1. Select **Save changes**. -### Configure a webhook +### With a webhook -If you are unable to provide GitLab with your Jenkins server login, you can use this option -to integrate GitLab and Jenkins. +If you cannot [provide GitLab with your Jenkins server URL and authentication information](#with-a-jenkins-server-url), you can configure a webhook 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. In GitLab: + - [Create a webhook for your project](../user/project/integrations/webhooks.md#configure-a-webhook-in-gitlab). + - Enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`). + - 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. +- [GitLab Jenkins Integration](https://about.gitlab.com/solutions/jenkins/) +- [How to set up Jenkins on your local machine](../development/integrations/jenkins.md) +- [How to migrate from Jenkins to GitLab CI/CD](../ci/migration/jenkins.md) ## 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: +While configuring GitLab, you might get an error that states "Connection failed. Please check your settings". + +This issue has multiple possible causes and solutions: -- 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#allow-outbound-requests-to-certain-ip-addresses-and-domains). -- 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 [Jenkins plugin configuration](#configure-the-jenkins-server). +| Cause | Workaround | +|------------------------------------------------------------------|-------------| +| GitLab is unable to reach your Jenkins instance at the address. | If your GitLab instance is self-managed, ping 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#allow-outbound-requests-to-certain-ip-addresses-and-domains).| Add the instance to the GitLab installation's allowlist. | +| The credentials for the Jenkins instance do not have sufficient access or are invalid.| Grant the credentials sufficient access or create valid credentials. | +|The **Enable authentication for `/project` end-point** checkbox is not selected in your [Jenkins plugin configuration](#configure-the-jenkins-server)| Select the checkbox. | ### 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). +You might get an error that states `Could not connect to the CI server` in a merge +request if GitLab did not receive a build status update from Jenkins through 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. +This issue occurs when Jenkins is not properly configured or there is an error +reporting the status through the API. -To fix this issue, ensure you: +To fix this issue: 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. +1. [Configure the Jenkins project](#configure-the-jenkins-project), and make sure + that, if you create a freestyle project, you choose the "Publish build status to GitLab" + post-build action. ### Merge request event does not trigger a Jenkins pipeline |