About Pipeline Multibranch Defaults Plugin

Table of Contents

Warnings
Security implications
How it works
How to configure
Example default Jenkinsfile
- Default scripted pipeline
- Default declarative pipeline
Example Job DSL configuration
Additional recommended plugins
Release Notes
Authors
License

Normally, Jenkins pipelines and Multibranch pipelines requires a developer to save a Jenkinsfile in their repository root on one or more branches. The Pipeline Multibranch Defaults Plugin allows a Jenkins administrator to specify a default Jenkinsfile so that developers do not need to have a Jenkinsfile in their repository.

This is useful because:

Jenkins Administrators can define a default Jenkinsfile in which all repositories can use. This makes it easy to centralize build configuration for all projects.
Jenkins Administrators can define a set of required steps before and after a developer Jenkinsfile is run, but still run the normal repository Jenkinsfile by calling it with the load step. For example,
- Security analysis can be run as a required step before running a user Jenkinsfile.
- An Audit step can be run as a required step after running a user Jenkinsfile which might do things like archive the build logs and update ticketing systems with a download link to the archived logs. This is great for organizations which have compliance and regulations to meet by governing bodies.

Warnings

Pipeline multibranch defaults plugin v1.1 and older created a new Job type named Multibranch Pipeline with defaults. This is considered a design flaw.

Pipeline multibranch defaults plugin v2.0 and later allow specifying a default Jenkinsfile directly with a normal Multibranch Pipeline. If you're using v2.0 or later of this plugin do not use the "Multibranch Pipeline with defaults" project type. It will be removed from later releases of this plugin.

Security implications

This plugin supports running a default Jenkinsfile with or without a pipeline sandbox. If the pipeline load step is used, then the default Jenkinsfile must be run with sandbox enabled. Otherwise, unauthorized developer code will be able to run within and modify the Jenkins server runtime. This basically means all developers with commit access can affect any part of the Jenkins infrastructure (malicious or not). This is essentially the same security implications as granting developers access to the script console.

How it works

Configuration files will be referenced from the global Jenkins script store provided by the config-file provider plugin. If a multibranch pipeline is configured to use a default Jenkinsfile, then the following happens:

Every branch discovered is assumed to have a Jenkinsfile because of the default Jenkinsfile setting.
Every pull request discovered is assumed to have a Jenkinsfile because of the default Jenkinsfile setting.
When discover tags is enabled, every tag is assumed to have a Jenkinsfile because of the default Jenkinsfile setting.

How to configure

This section explains how to configure a multibranch pipeline to use the default Jenkinsfile feature provided by this plugin.

Create a default Jenkinsfile

Before pipelines can be configured to use a default Jenkinsfile, one must configure a groovy script in the global Config File Management provided by the Configfile-Provider Plugin.

Visit Manage Jenkins menu.
Visit Manage files menu.
Add a new config file of type Groovy file. During this step you can give your config file the Script ID Jenkinsfile or whatever ID you would like. Leaving it to be a UUID is fine as well.
Fill in the settings for the config file.

Note: versions prior to the pipeline multibranch defaults plugin v2.0 required the Script ID to be "Jenkinsfile". This is no longer required.

Create a Multibranch Pipeline job

Create a new multibranch pipeline job as one normally would (or update an existing multibranch pipeline job). In the menu on the left, choose New Item and select multibranch pipeline.

Update the build configuration mode

Under the Build Configuration section there will be a Mode setting. Change the Mode to "by default Jenkinsfile".

Configurable options include:

Script ID - The ID of the default Jenkinsfile to use from the global Config File Management.
Run default Jenkinsfile within Groovy sandbox - If enabled, the configured default Jenkinsfile will be run within a Groovy sandbox. This option is strongly recommended if the Jenkinsfile is using the load pipeline step to evaluate a groovy source file from an SCM repository.

Note: if disabling the groovy sandbox, then admin script approval may be required the first time the default Jenkinsfile is used.

Example default Jenkinsfile

Default scripted pipeline

A default scripted pipeline Jenkinsfile which does not allow user a repository Jenkinsfile to run.

node {
    stage("Hello world") {
        echo "Hello world"
    }
}

A default scripted pipeline Jenkinsfile which loads a repository Jenkinsfile. Use case is adding required security scans or additional auditing steps.

node('security-scanner') {
    stage('Pre-flight security scan') {
        checkout scm
        sh '/usr/local/bin/security-scan.sh'
    }
}
try {
    node {
        stage('Prepare Jenkinsfile environment') {
            checkout scm
        }
        // now that SCM is checked out we can load and execute the repository
        // Jenksinfile
        load 'Jenkinsfile'
    }
} catch(Exception e) {
    throw e
} finally {
    stage('Post-run auditing') {
        // do some audit stuff here
    }
}

Default declarative pipeline

Using declarative pipeline as your default Jenkinsfile is also possible. Here's an example:

pipeline {
    agent none
    stages {
        stage('Pre-flight security scan') {
            agent 'security-scanner'
            steps {
                sh '/usr/local/bin/security-scan.sh'
            }
        }
        stage('Load user Jenkinsfile') {
            agent any
            steps {
                load 'Jenkinsfile'
            }
        }
    }
    post {
        always {
            stage('Post-run auditing') {
                // do some audit stuff here
            }
        }
    }
}

Example Job DSL configuration

multibranchPipelineJob('example') {
    // SCM source or additional configuration

    factory {
        pipelineBranchDefaultsProjectFactory {
            // The ID of the default Jenkinsfile to use from the global Config
            // File Management.
            scriptId 'Jenkinsfile'

            // If enabled, the configured default Jenkinsfile will be run within
            // a Groovy sandbox.
            useSandbox true
        }
    }
}

Additional recommended plugins

The following plugins are recommended as great companion plugins to the pipeline multibranch with defaults plugin.

Basic Branch Build Strategies Plugin provides some basic branch build strategies for use with Branch API based projects. This plugin is especially good at limiting tags built. This is good for projects adopting a tag-based workflow.
SCM Filter Branch PR Plugin provides wildcard and regex filters for multibranch pipelines which include matching the destination branch of PRs with the filters. This is necessary if one does not want all branches for a project to be matched by the default Jenkinsfile. This also allows one to filter tags as well.
Job DSL plugin allows Jobs and Views to be defined via DSLs. Multibranch pipelines can be automatically created with a default Jenkinsfile configured. This plugin provides configuration as code for jobs.

Release Notes

For release notes see CHANGELOG.

Authors

Saponenko Denis - Initial work - vaimr
Sam Gleske - plugin maintainer since Sep 29, 2018

See also the list of contributors who participated in this project.

License

The MIT License

lhotakj / pipeline-multibranch-defaults-plugin