Job DSL Commands

NOTE: See the API Viewer for details about all options.

DSL Methods

The DSL execution engine exposes several methods to create Jenkins jobs, views, folders and config files. These methods imply the creation of a Jenkins item and the closure to the method can be used to define the item's settings. The only mandatory option is the item's name.

job('my-job')

When defining jobs, views or folders the name is treated as absolute to the Jenkins root by default, but the seed job can be configured to interpret names relative to the seed job. (since 1.24)

In the closure provided to the job methods there are a few top level methods, like label and description. Others are nested deeper in blocks which represent their role in Jenkins, e.g. the publishers block contains all the publisher actions.

DSL methods can be cumulative or overriding, meaning that some methods will add nodes (e.g. publishers and steps) and some will replace nodes (e.g. disabled will replace any existing disabled nodes). Some methods like scm and multiscm are mutually exclusive. Likewise, when using the scm block, only one SCM can be specified.

NOTE: when using these methods, remember that you need to use them in context. I.e. to use the downstream method, it needs to be enclosed in a publishers context.

The plugin tries to provide DSL methods to cover "common use case" scenarios as simple method calls. When these methods fail you, you can always generate the underlying XML yourself via The Configure Block. Sometimes, a DSL method will provide a configure block of its own, which will set the a good context to help modify a few fields. This gives native access to the job config XML, which is typically very straight forward to understand.

(Note: The full XML can be found for any job, view or folder by taking the Jenkins URL and appending /config.xml to it. We find that creating a job the way you like it, then viewing the XML is the best way to learn what fields you need.)

Job

The DSL exposes several methods to create jobs of different types.

job(String name, Closure closure = null)          // since 1.30, an alias for freeStyleJob

freeStyleJob(String name, Closure closure = null) // since 1.30

buildFlowJob(String name, Closure closure = null) // since 1.30

ivyJob(String name, Closure closure = null)       // since 1.38

matrixJob(String name, Closure closure = null)    // since 1.30

mavenJob(String name, Closure closure = null)     // since 1.30

multiJob(String name, Closure closure = null)     // since 1.30

pipelineJob(String name, Closure closure = null)  // since 1.47

multibranchPipelineJob(String name, Closure closure = null) // since 1.47

These methods will return a job object that can be re-used and passed around. E.g.

def myJob = freeStyleJob('SimpleJob')
myJob.with {
    description 'A Simple Job'
}

See the API Viewer page for details about all job options.

View

To create views, the DSL provides the following methods.

listView(String name, Closure closure = null)             // since 1.30

sectionedView(String name, Closure closure = null)        // since 1.30

nestedView(String name, Closure closure = null)           // since 1.30

deliveryPipelineView(String name, Closure closure = null) // since 1.30

buildPipelineView(String name, Closure closure = null)    // since 1.30

buildMonitorView(String name, Closure closure = null)     // since 1.30

categorizedJobsView(String name, Closure closure = null)  // since 1.31

The view methods behaves like the job methods and will return a view object.

See the API Viewer page for details about view options.

Folder

When the CloudBees Folders Plugin has been installed, the DSL can be used to create folders.

folder(String name, Closure closure = null) // since 1.30

The folder methods behaves like the job methods and will return a folder object.

See the API Viewer page for details about folder options.

Folders will be created before jobs and views to ensure that a folder exists before entries are created.

Items can be created within folders by using the full path as job name.

folder('project-a')

freeStyleJob('project-a/compile')

listView('project-a/pipeline')

folder('project-a/testing')

Config File

When the Config File Provider Plugin has been installed, the DSL can be used to create configuration files.

configFiles(Closure configFilesClosure = null)                         // since 1.58

customConfigFile(String name, Closure configFileClosure = null)        // deprecated

mavenSettingsConfigFile(String name, Closure configFileClosure = null) // deprecated

The configFiles method can be used to create any kind of config file that is supported by the Dynamic DSL. Use the embedded API viewer to browse available methods.

The other methods behaves like the job methods and will return a config file object, but these methods are deprecated and will be removed. See the API Viewer page for details about these methods.

Config files will be created before jobs to ensure that the file exists before it is referenced.

customConfigFile('my-config') {
  comment('My important configuration')
  content('<some-xml/>')
}

mavenSettingsConfigFile('central-mirror') {
  content readFileFromWorkspace('maven-settings/central-mirror.xml')
}

Queue

queue(String jobName)
queue(Job job)

This provide the ability to schedule a job to be executable after the DSL runs. The given name doesn't have to be a job which was generated by the DSL, but it could be.

Reading Files from Workspace

InputStream streamFileFromWorkspace(String filePath)
String readFileFromWorkspace(String filePath)
String readFileFromWorkspace(String jobName, String filePath) // since 1.25

With the first two variants, you can read in a file from the current workspace anywhere in the script. This assumes that you checked out some source control as part of the job processing the DSL. This can be useful when populating fields on a generated job, e.g.

job('example') {
    steps {
        shell(readFileFromWorkspace('build.sh'))
    }
}

And with the third variant, you can read a file from the workspace of any job. This can be used to set the description of a job from a file in the job's workspace. The method will return null when the job or the file does not exist or the job has no workspace, e.g. when it has not been built yet.

job('acme-tests') {
    description(readFileFromWorkspace('acme-tests', 'README.txt'))
}

(since 1.15)

Uploading User Content

Jenkins has a mechanism called User Content, which allows arbitrary files to be served from http://yourhost/jenkins/userContent.

User content can be uploaded to Jenkins with the userContent DSL method.

userContent(String path, InputStream content)

In conjunction with streamFileFromWorkspace, any content can be upload from the seed job's workspace.

userContent('acme.png', streamFileFromWorkspace('images/acme.png'))

(since 1.33)

Logging

Each DSL script provides a variable called out which points to a PrintStream. It defines methods like println which can be used to log messages to the build log (Console Output). This can be useful for debugging complex DSL scripts.

out.println('Hello from a Job DSL script!')

out is only available in scripts, but not in any classes used by a script, even if a class is defined in a script. In this case, out must be passed into any method for logging.

class Helper {
    static doSomething(def out) {
        out.println('Hello from a Job DSL helper class!')
    }
}

Helper.doSomething(out)

When used in a script directly, out can be omitted.

println('Hello from a Job DSL script!')

If the log output should go to the Jenkins log, java.util.logging must be used.

import java.util.logging.Logger

Logger logger = Logger.getLogger('org.example.jobdsl')
logger.info('Hello from a Job DSL script!')

This works in scripts and classes. See Logging for details.

Configure

When an option is not supported by the Job DSL, then The Configure Block can be used for extending the DSL.

Here is a simple example which adds a EnvInjectPasswordWrapper node:

job('example') {
    ...
    configure { project ->
        project / buildWrappers / EnvInjectPasswordWrapper {
            injectGlobalPasswords(true)
        }
    }
}

See The Configure Block page for details.

DSL Factory

Because the engine is just Groovy, you can call other Groovy classes on the classpath. When in those methods the job method is no longer available, so it is recommended to pass in the current context to make this method available to another context. For example, when making utility methods, you would call them like this:

BuildFramework.ant(this, 'my-ant-project', 'clean build')

Then the BuildFramework class has everything it needs to make job calls:

class BuildFramework {
    static ant(dslFactory, jobName, antTargets) {
        dslFactory.job(jobName) {
            steps {
                ant(antTargets)
            }
        }
    }
}

Script Location

The absolute path of the executing script file is available as __FILE__ variable.

println("script directory: ${new File(__FILE__).parent.absolutePath}")

The __FILE__ variable is available in scripts only, not in any classes used by a script.

Job DSL scripts are executed on the Jenkins master node, but the seed job's workspace which contains the script files may reside on a build node. This mean that direct access to the file specified by __FILE__ may not be possible from a DSL script. See Distributed builds for details.

Seed Job

Access to the seed job is available through the SEED_JOB variable. The variable contains a reference to the internal Jenkins object that represents the seed job. The actual type of the object depends on the type of job that runs the DSL. For a freestyle project, the object is an instance of hudson.model.FreeStyleProject. See the Jenkins API Documentation for details.

The SEED_JOB variable is only available in scripts, not in any classes used by a script. And it is only available when running in Jenkins, e.g. in the "Process Job DSLs" build step.

The following example show how to apply the same quiet period for a generated job as for the seed job.

job('example') {
    quietPeriod(SEED_JOB.quietPeriod)
}