Merge pull request #1187 from daspilker/JENKINS-43693

[JENKINS-43693] improve multi-branch pipeline support

Author: daspilker

docs/Home.md

@@ -33,6 +33,9 @@ Browse the Jenkins issue tracker to see any [open issues](https://issues.jenkins
 
 ## Release Notes
 * 1.75 (unreleased)
+  * Added documentation about mandatory identifier in multi-branch Pipeline job branch sources, the identifier will no
+    longer be generated and must be set to a constant and unique value, see [Migration](Migration#migrating-to-175)
+    ([JENKINS-43693](https://issues.jenkins-ci.org/browse/JENKINS-43693))
   * Enhanced support for the [Branch API Plugin](https://plugins.jenkins.io/branch-api)
     ([JENKINS-54877](https://issues.jenkins-ci.org/browse/JENKINS-54877))
   * Fixed [[Dynamic DSL]] problem

docs/Migration.md

@@ -1,3 +1,29 @@
+## Migrating to 1.75
+
+The `id` option in the Git and GitHub branch source contexts is now mandatory
+([JENKINS-43693](https://issues.jenkins-ci.org/browse/JENKINS-43693)).
+
+DSL prior to 1.75
+```groovy
+multibranchPipelineJob('example') {
+    branchSources {
+        github {
+        }
+    }
+}
+```
+
+DSL since 1.75
+```groovy
+multibranchPipelineJob('example') {
+    branchSources {
+        github {
+            id('12312313') // IMPORTANT: use a constant and unique identifier
+        }
+    }
+}
+```
+
 ## Migrating to 1.72
 
 ### CloudBees Folders Plugin

job-dsl-core/src/main/docs/examples/javaposse/jobdsl/dsl/DslFactory/multibranchPipelineJob.groovy

@@ -1,6 +1,7 @@
 multibranchPipelineJob('example') {
     branchSources {
         git {
+            id('123456789') // IMPORTANT: use a constant and unique identifier
             remote('https://github.com/jenkinsci/job-dsl-plugin.git')
             credentialsId('github-ci')
             includes('JENKINS-*')

job-dsl-core/src/main/docs/examples/javaposse/jobdsl/dsl/helpers/workflow/BranchSourcesContext/git.groovy

@@ -1,6 +1,7 @@
 multibranchPipelineJob('example') {
     branchSources {
         git {
+            id('12121212') // IMPORTANT: use a constant and unique identifier
             remote('https://github.com/jenkinsci/job-dsl-plugin.git')
             credentialsId('github-ci')
             includes('JENKINS-*')

job-dsl-core/src/main/docs/examples/javaposse/jobdsl/dsl/helpers/workflow/BranchSourcesContext/github.groovy

@@ -1,6 +1,7 @@
 multibranchPipelineJob('example') {
     branchSources {
         github {
+            id('23232323') // IMPORTANT: use a constant and unique identifier
             scanCredentialsId('github-ci')
             repoOwner('OwnerName')
             repository('job-dsl-plugin')

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/DslFactory.groovy

@@ -130,6 +130,8 @@ interface DslFactory extends ViewFactory {
     /**
      * Create or updates a multibranch pipeline job.
      *
+     * <b>IMPORTANT</b>: Make sure that each branch source has a constant and unique identifier.
+     *
      * @since 1.47
      * @see #multibranchPipelineJob(java.lang.String, groovy.lang.Closure)
      */
@@ -156,6 +158,8 @@ interface DslFactory extends ViewFactory {
     /**
      * Creates or updates a multibranch pipeline job.
      *
+     * <b>IMPORTANT</b>: Make sure that each branch source has a constant and unique identifier.
+     *
      * @since 1.47
      */
     @RequiresPlugin(id = 'workflow-multibranch', minimumVersion = '2.10', failIfMissing = true)

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/workflow/BranchSourcesContext.groovy

@@ -6,6 +6,7 @@ import javaposse.jobdsl.dsl.ContextType
 import javaposse.jobdsl.dsl.DslContext
 import javaposse.jobdsl.dsl.Item
 import javaposse.jobdsl.dsl.JobManagement
+import javaposse.jobdsl.dsl.Preconditions
 import javaposse.jobdsl.dsl.RequiresPlugin
 
 @ContextType('jenkins.branch.BranchSource')
@@ -24,6 +25,8 @@ class BranchSourcesContext extends AbstractExtensibleContext {
         GitBranchSourceContext context = new GitBranchSourceContext()
         ContextHelper.executeInContext(branchSourceClosure, context)
 
+        Preconditions.checkNotNullOrEmpty(context.id, 'id must be specified')
+
         branchSourceNodes << new NodeBuilder().'jenkins.branch.BranchSource' {
             source(class: 'jenkins.plugins.git.GitSCMSource') {
                 id(context.id)
@@ -49,6 +52,8 @@ class BranchSourcesContext extends AbstractExtensibleContext {
         GitHubBranchSourceContext context = new GitHubBranchSourceContext(jobManagement)
         ContextHelper.executeInContext(branchSourceClosure, context)
 
+        Preconditions.checkNotNullOrEmpty(context.id, 'id must be specified')
+
         branchSourceNodes << new NodeBuilder().'jenkins.branch.BranchSource' {
             source(class: 'org.jenkinsci.plugins.github_branch_source.GitHubSCMSource') {
                 id(context.id)

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/workflow/GitBranchSourceContext.groovy

@@ -3,7 +3,7 @@ package javaposse.jobdsl.dsl.helpers.workflow
 import javaposse.jobdsl.dsl.Context
 
 class GitBranchSourceContext implements Context {
-    String id = UUID.randomUUID()
+    String id
     String remote
     String credentialsId
     String includes = '*'

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/helpers/workflow/GitHubBranchSourceContext.groovy

@@ -4,7 +4,7 @@ import javaposse.jobdsl.dsl.AbstractContext
 import javaposse.jobdsl.dsl.JobManagement
 
 class GitHubBranchSourceContext extends AbstractContext {
-    String id = UUID.randomUUID()
+    String id
     String apiUri
     String scanCredentialsId
     String checkoutCredentialsId = 'SAME'

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/jobs/MultibranchWorkflowJob.groovy

@@ -14,6 +14,8 @@ class MultibranchWorkflowJob extends ComputedFolder {
 
     /**
      * Adds branch sources.
+     *
+     * <b>IMPORTANT</b>: Make sure that each branch source has a constant and unique identifier.
      */
     void branchSources(@DslContext(BranchSourcesContext) Closure sourcesClosure) {
         BranchSourcesContext context = new BranchSourcesContext(jobManagement, this)