Using Job DSL Plugin

1. Understanding Job DSL Concept

The Jenkins Job DSL Plugin allows you to define jobs in a Groovy-based domain-specific language (DSL). This approach enables the declarative creation and management of Jenkins jobs, making it easier to version control, reuse, and automate job configurations.

Feature	Description	Notes
Declarative Job Definition	Jobs are defined using Groovy scripts that describe job configurations.	Scripted jobs can be generated from templates or existing jobs.
Job Creation	Jobs can be created, updated, or deleted via DSL scripts.	Supports both new job creation and modification of existing ones.
Version Control	DSL scripts can be stored in version control systems like Git.	Enables collaboration and auditability of job configurations.
Reusability	DSL scripts can include shared configuration blocks or templates.	Reduces redundancy in job definitions across multiple projects.

Example: Basic Job DSL Script

job('example-job') {
    description('An example job defined using Job DSL')
    scm {
        git('https://github.com/example/repo.git', 'main')
    }
    triggers {
        scm('H/5 * * * *')
    }
    steps {
        shell('echo "Hello World"')
    }
}

Note: The Job DSL plugin uses Groovy syntax, which means it supports all standard Groovy features including closures and methods.

2. Creating Seed Jobs

Seed jobs are used to generate Jenkins jobs dynamically using the Job DSL plugin. They act as a template or source for creating multiple jobs.

Property	Description	Example
Seed Job Name	Name of the seed job	`my-seed-job`
Script Path	Path to the Job DSL script	`jobs/job-dsl.groovy`
Build Configuration	How the seed job is built	`Build when a change is pushed to SCM`

Example: Seed Job Configuration

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    // Example of a seed job DSL script
                    job('example-job') {
                        description('An example job created from a seed')
                        steps {
                            shell('echo "Hello World"')
                        }
                    }
                }
            }
        }
    }
}

Note: The Job DSL script must be written in Groovy and should define the jobs to be created.

3. Writing Job DSL Scripts

Property	Description	Example
job	Defines a new job in Jenkins	`job('my-job') {`
description	Sets the description of the job	`description('This is my job')`
scm	Configures the SCM (Source Control Management) for the job	`scm { git('https://github.com/example/repo.git') }`
triggers	Defines triggers that start the job	`triggers { pollSCM('H/15 * * * *') }`
steps	Defines the build steps to execute	`steps { shell('echo Hello World') }`

Example: Basic Job Definition

job('example-job') {
    description('A sample job defined with Job DSL')
    scm {
        git('https://github.com/example/repo.git')
    }
    triggers {
        pollSCM('H/15 * * * *')
    }
    steps {
        shell('echo "Building..."')
    }
}

Example: Multibranch Pipeline Job

multibranchPipelineJob('my-multibranch') {
    description('Multibranch pipeline job')
    branchSources {
        git {
            remote('https://github.com/example/repo.git')
            credentialsId('github-credentials')
        }
    }
}

Note: Job DSL scripts are written in Groovy and executed by the Jenkins Job DSL plugin. Ensure that the script is valid Groovy syntax to avoid runtime errors.

4. Generating Freestyle Jobs

Property	Description	Example
name	Name of the freestyle job	`my-freestyle-job`
description	Description of the job	`Builds a simple project`
scm	Source control management configuration	`git("https://github.com/user/repo.git")`
triggers	Triggers for job execution	`pollSCM("H/5 * * * *")`
builders	Build steps to execute	`shell("echo 'Hello World'")`
publishers	Publishing actions after build	`archiveArtifacts("*.jar")`

Example: Creating a Freestyle Job

job("my-freestyle-job") {
    description("Builds a simple project")
    scm {
        git("https://github.com/user/repo.git")
    }
    triggers {
        pollSCM("H/5 * * * *")
    }
    builders {
        shell("echo 'Hello World'")
    }
    publishers {
        archiveArtifacts("*.jar")
    }
}

5. Generating Pipeline Jobs

Property	Description	Example
pipelineJob	Creates a new pipeline job using Job DSL	`pipelineJob('my-pipeline') {`
definition	Defines the pipeline script	`definition { cps { script('pipelineScript') } }`
script	Inline script content for the pipeline	`script('echo "Hello World"')`

Example: Creating a Pipeline Job

pipelineJob('example-pipeline') {
    definition {
        cps {
            script('''
                pipeline {
                    agent any
                    stages {
                        stage('Build') {
                            steps {
                                echo 'Building...'
                            }
                        }
                    }
                }
            ''')
        }
    }
}

Note: The pipelineJob block must be inside a job or jobs block to be valid in Jenkins Job DSL.

6. Generating Multibranch Jobs

Property	Description	Example
name	Name of the multibranch pipeline job	`"my-multibranch-pipeline"`
scm	Source Control Management configuration	`[ "type": "git", "url": "https://github.com/example/repo.git" ]`
triggers	Triggers to start builds (e.g., SCM polling)	`["SCMTrigger": ["scm": "/5 * * *"]]`

Example: Define Multibranch Pipeline

job("my-multibranch-pipeline") {
    scm {
        git("https://github.com/example/repo.git")
    }
    triggers {
        scm("*/5 * * * *")
    }
}

Note: The Job DSL plugin supports defining multibranch pipelines using Groovy syntax. These jobs can be configured to poll SCM or trigger builds based on changes.

7. Configuring Job Properties via DSL

Property	Description	Example
name	Job name	`"my-job"`
description	Job description	`"A sample Jenkins job"`
project	Project type (freestyle, pipeline)	`"pipeline"`
scm	Source control management configuration	`git("https://github.com/example/repo.git")`
triggers	Build triggers (e.g., SCM polling, scheduled)	`pollSCM("H/5 * * * *")`
builders	Build steps (e.g., shell, maven)	`shell("echo 'Hello World'")`
publishers	Post-build actions (e.g., archive, email)	`archiveArtifacts("*.jar")`
parameters	Build parameters (e.g., string, boolean)	`stringParam("ENV", "prod")`

Example: Defining a Job with Properties

job("example-job") {
    description("A sample job demonstrating DSL properties")
    project("pipeline")
    scm {
        git("https://github.com/example/repo.git")
    }
    triggers {
        pollSCM("H/5 * * * *")
    }
    builders {
        shell("echo 'Building...'\nls -la")
    }
    publishers {
        archiveArtifacts("*.jar")
    }
}

8. Using DSL Templates

DSL templates allow you to define reusable job configurations that can be instantiated with different parameters. This promotes consistency and reduces duplication in your Jenkins jobs.

Template Type	Description	Usage
Job Template	Reusable configuration for creating jobs with common properties.	Define a template using `job { ... }` and apply it with parameters.
Pipeline Template	Reusable pipeline definitions that can be parameterized.	Use `pipelineJob { ... }` to define and reuse pipelines.

Example: Creating a Job Template

jobTemplate {
    name 'my-template'
    description 'A reusable job template'
    properties {
        disabled()
    }
    steps {
        shell('echo "Hello from template"')
    }
}

Example: Using a Job Template

job('my-job') {
    template 'my-template'
    parameters {
        stringParam('ENV', 'dev', 'Environment to deploy to')
    }
}

Note: Templates must be defined before they are used in job definitions.

Warning: Template parameters are not validated at compile time, so ensure proper handling in the job logic.

9. Managing Job Hierarchies

Job hierarchies in Jenkins help organize jobs into a structured tree, making it easier to manage and navigate large numbers of jobs. This is particularly useful in environments with many related jobs.

Property	Description	Example
Folder Plugin	Enables creation of hierarchical job structures using folders.	`org.jenkinsci.plugins.workflow.job.WorkflowJob`
Nested Jobs	Jobs can be nested inside folders to create a hierarchy.	`folder1/folder2/jobName`
Job DSL Script	Used to define jobs and their hierarchy in code.	`job('myJob') { ... }`

Example: Creating a Folder Hierarchy

folder('projectA') {
    description('Main project folder')
}

folder('projectA/services') {
    description('Service jobs')
}

job('projectA/services/api') {
    description('API service job')
    steps {
        shell('echo "Running API service..."')
    }
}

Example: Using Folder Properties

folder('production') {
    properties {
        folderCredentials {
            credential {
                id('prod-db-credentials')
                description('Database credentials for production')
                scope('GLOBAL')
            }
        }
    }
}

Note: Folder hierarchies can be managed via the Jenkins UI or through Job DSL scripts. Using Job DSL allows for version-controlled, repeatable job structures.

10. Testing DSL Scripts

Example: Basic Job DSL Test

import com.cloudbees.hudson.plugins.modeling.JobTemplate
import com.cloudbees.hudson.plugins.modeling.ModelObject
import jenkins.model.Jenkins

def jobName = 'test-job'
def jobXml = """
<project>
  <description>Test Job</description>
  <builders>
    <hudson.tasks.Shell>
      <command>echo 'Hello World'</command>
    </hudson.tasks.Shell>
  </builders>
</project>
"""

// Create a test job using the DSL
def job = Jenkins.instance.createProjectFromXML(jobName, new ByteArrayInputStream(jobXml.getBytes()))
println "Created job: ${job.name}"

Test Type	Description	Tools
Unit Testing	Testing individual DSL scripts or functions in isolation	`JUnit`, `Spock`
Integration Testing	Testing DSL scripts in a Jenkins environment with dependencies	`Jenkins Pipeline`, `Job DSL`
End-to-End Testing	Testing full job creation and execution flow	`Jenkins Integration Tests`, `Acceptance Testing`

Note: Use JobTemplate to simulate job creation in tests.

Warning: Avoid modifying live Jenkins instances during tests.

Testing Best Practices

Use JobTemplate to mock job creation
Validate DSL script syntax before running tests
Run unit tests in isolation to avoid side effects
Use Jenkins Pipeline for integration testing

11. Version Controlling DSL Scripts

Option	Values	Notes
job.dsl.script	`script.groovy`	Path to the DSL script file
job.dsl.repository	`https://github.com/example/jenkins-dsl.git`	Git repository URL containing DSL scripts
job.dsl.branch	`main`	Branch to checkout DSL scripts from
job.dsl.credentials	`git-credentials-id`	Credentials ID for Git authentication

Example: Configure DSL Script Version Control

job('example-job') {
    definition {
        cps {
            scriptPath 'scripts/example.groovy'
        }
    }
}

Note: Ensure the Jenkins user has read access to the version-controlled repository.

Warning: Changes to DSL scripts must be committed and pushed to the repository for Jenkins to pick them up.