diff --git a/README.md b/README.md index fbcaec3..845bf52 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ - [Pipeline jobs](#pipeline-jobs) - [Pipeline Multibranch jobs](#pipeline-multibranch-jobs) - [Job trigger configuration](#job-trigger-configuration) + - [Webhook URL](#webhook-url) - [Freestyle and Pipeline jobs](#freestyle-and-pipeline-jobs) - [Pipeline Multibranch jobs](#pipeline-multibranch-jobs-1) - [Multibranch Pipeline jobs with Job DSL](#multibranch-pipeline-jobs-with-job-dsl) @@ -201,26 +202,23 @@ node { ``` ## Job trigger configuration +### Webhook URL +When you configure the plugin to trigger your Jenkins job, by following the instructions below depending on job type, it will listen on a dedicated URL for JSON POSTs from GitLab's webhooks. That URL always takes the form ``http://JENKINS_URL/project/PROJECT_NAME``, or ``http://JENKINS_URL/project/FOLDER/PROJECT_NAME`` if the project is inside a folder in Jenkins. **You should not be using** ``http://JENKINS_URL/job/PROJECT_NAME/build`` or ``http://JENKINS_URL/job/gitlab-plugin/buildWithParameters``, as this will bypass the plugin completely. + ### Freestyle and Pipeline jobs 1. In the *Build Triggers* section: * Select *Build when a change is pushed to GitLab* - * Copy the *GitLab webhook URL* appearing on the same line with *Build when a change is - pushed to GitLab* + * Copy the *GitLab webhook URL* shown in the UI (see [here](#webhook-url) for guidance) * Use the check boxes to trigger builds on *Push Events* and/or *Created Merge Request Events* and/or *Accepted Merge Request Events* and/or *Closed Merge Request Events* - * Optionally use *Rebuild open Merge Requests* to enable re-building open merge requests after a - push to the source branch - * If you selected *Rebuild open Merge Requests* other than *None*, check *Comments*, and specify the - *Comment for triggering a build*. A new build will be triggered when this phrase appears in a - commit comment. In addition to a literal phrase, you can also specify a Java regular expression - * You can use *Build on successful pipeline events* to trigger on a successful pipeline run in Gitlab. Note that - this build trigger will only trigger a build if the commit is not already built and does not set the Gitlab status. - Otherwise you might end up in a loop + * Optionally use *Rebuild open Merge Requests* to enable re-building open merge requests after a push to the source branch + * If you selected *Rebuild open Merge Requests* other than *None*, check *Comments*, and specify the *Comment for triggering a build*. A new build will be triggered when this phrase appears in a commit comment. In addition to a literal phrase, you can also specify a Java regular expression + * You can use *Build on successful pipeline events* to trigger on a successful pipeline run in Gitlab. Note that this build trigger will only trigger a build if the commit is not already built and does not set the Gitlab status. Otherwise you might end up in a loop 2. Configure any other pre build, build or post build actions as necessary 3. Click *Save* to preserve your changes in Jenkins 4. Create a webhook in the relevant GitLab projects (consult the GitLab documentation for instructions on this), and use the URL you copied from the Jenkins job configuration UI. It should look something like `http://JENKINS_URL/project/yourbuildname` ### Pipeline Multibranch jobs -Unlike other job types, there is no 'Trigger' setting required for a Multibranch job configuration; just create a webhook in GitLab for push requests which points to ``http://JENKINS_URL/project/PROJECT_NAME`` or ``http://JENKINS_URL/project/FOLDER/PROJECT_NAME`` if the project is inside a folder in Jenkins. When GitLab POSTs to this URL, it will trigger branch indexing for the Jenkins project, and Jenkins will handle starting any builds necessary. +Unlike other job types, there is no 'Trigger' setting required for a Multibranch job configuration; just create a webhook in GitLab for push requests which points to [the project's webhook URL.](#webhook-url) When GitLab POSTs to this URL, it will trigger branch indexing for the Jenkins project, and Jenkins will handle starting any builds necessary. If you want to configure some of the trigger options, such as the secret token or CI skip functionality, you can use a `properties` step. For example: