Generation

The branch seed job is responsible for the (re)generation of a branch pipeline.

Pipeline script

In the absence of any particular setup, the Seed plug-in will execute any seed/seed.groovy written in Jenkins Job DSL script and found in the branch. See Script Variables below to know which variables are available to your script.

Important points:

• Note that if no script is found, nothing will happen at all
• In all cases, the jobs, views and folders defined by this script will be created/updated at the same level as the branch seed job
• An item not defined any longer by the DSL script will be deleted

Sample script:

job("${SEED_PROJECT}-${SEED_BRANCH}-build") {
   description "Building the ${BRANCH} branch."
   parameters {
      stringParam('COMMIT', 'HEAD', 'Commit to build')
   }
   scm {
      git {
         remote {
             url PROJECT_SCM_URL
             branch "origin/${BRANCH}"
         }
         extensions {
             wipeOutWorkspace()
             localBranch BRANCH
         }
      }
   }
   steps {
      shell "Look! I'm building ${BRANCH}!"
   }
}

You can fire one (or several jobs) upon pipeline generation by using the queue method. For example:

queue "${SEED_PROJECT}-${SEED_BRANCH}-build"

Using pipeline libraries

In order to decrease the Jenkins Job DSL code duplication between projects, you can create [pipeline libraries](Pipeline library) and refer to them in a seed/seed.properties property file instead.

The properties are:

• seed.dsl.libraries - a comma-separated list of dependency notations, used to download JAR libraries that can then be referred from the DSL script - it defaults to nothing (empty list)

Example:

seed.dsl.libraries = com.yourcompany:your-dsl-library:1.0.1

Note that all transitive dependencies of the declared libraries will also be downloaded.

• seed.dsl.repository - a URL to a repository to download the libraries from. It defaults to none, meaning that the libraries are downloaded from the Maven Central repository. If the property is prefixed by flat:, the rest of the property is taken as a file path (relative to the seed directory), used as a flat repository
• seed.dsl.repository.user and seed.dsl.repository.password - optional user and password to use to connect to the Seed repository, if defined. Its value is evaluated using the Jenkins context and can therefore use environment variables, like ${MY_REPOSITORY_USER}, defined globally
• seed.dsl.script.jar - defines the library which contains the DSL script to execute. If not defined, the script is assumed to be provided by the branch, directly in seed/seed.groovy
• seed.dsl.script.location - defines the path to the DSL script in the JAR defined above. It defaults to seed.groovy - see the [documentation](Pipeline library) to know how to define a pipeline library

The rest of the properties can be used by the [pipeline library](Pipeline library) in order to get its configuration parameters.

Mixing script and pipeline libraries

You can mix both the seed/seed.groovy approach - DSL code - and the seed/seed.properties one - pipeline library.

If both files are provided, the DSL script embedded in the pipeline library is ignored (and I recommend to remove any seed.dsl.script.jar property) and only the seed/seed.groovy code will be executed.

However, the script in seed/seed.groovy will be able to import and use classes and methods defined in the pipeline libraries.

Enforcing pipeline libraries

In some cases, you might want to forbid projects to provide their own DSL code and to enforce the use of pipeline libraries only.

You can do this as [seed](Quick start) level by setting the Disable DSL scripts configuration parameter to Yes.

Script variables

The DSL scripts defined in the project and/or in a pipeline library have access to the following variables, provided at runtime by the Seed plug-in itself.

• PROJECT - raw project name
• PROJECT_SCM_TYPE - git or svn
• PROJECT_SCM_URL - the base SCM URL for the project
• PROJECT_SCM_CREDENTIALS - UUID of the [Jenkins credentials](SCM credentials) to use
• BRANCH - basic branch name in the SCM, like branches/xxx in SVN or the branch name in Git

Additionally:

• SEED_PROJECT - project normalized name
• SEED_BRANCH - branch normalized name

Note that you can define additional parameters to be entered at branch generation time - see Extensions for more information.

Use cases and samples

Simple DSL script

In your branch:

seed/
   seed.groovy

With seed.groovy:

job("${SEED_PROJECT}-${SEED_BRANCH}-build") {
    logRotator(-1, 40)
    parameters {
        stringParam('COMMIT', 'HEAD', 'Commit to build')
    }
    scm {
        git {
            remote {
                url "git@github.com:nemerosa/seed-plugin.git"
                branch '${COMMIT}'
            }
            wipeOutWorkspace()
            localBranch "${BRANCH}"
        }
    }
    steps {
        gradle 'clean localDockerAcceptanceTest --info --profile'
    }
    publishers {
        archiveJunit("**/build/test-results/*.xml")
        tasks(
                '**/*.java,**/*.groovy,**/*.xml,**/*.html,**/*.js',
                '**/build/**',
                'FIXME', 'TODO', '@Deprecated', true
        )
    }
}

DSL script with libraries (mixed mode)

If your DSL script needs extra dependencies:

seed/
   seed.properties
   seed.groovy

with seed.properties:

seed.dsl.libraries=group:artifact:version

and seed.groovy:

job("${SEED_PROJECT}-${SEED_BRANCH}-build") {
   // Using classes from group:artifact:version
}

Using a template library

seed/
   seed.properties

with seed.properties:

seed.dsl.libraries=group:artifact:version
seed.dsl.script.jar=artifact

The seed.groovy file will be available as a resource in the artifact.jar file.

See also

• [SCM credentials](SCM credentials)
• [Creating a pipeline library](Pipeline library)