Setting up a Pipeline Template

Pipeline Templates are stored under a /templates folder in your source code repository, and each Pipeline Template is defined as a subfolder containing two files:

Jenkinsfile: A standard Pipeline Jenkinsfile, which supports either Declarative Pipeline syntax or Groovy scripting.
template.yaml: A YAML file containing the template’s parameters.

To set up a Pipeline Template, create the subfolder for each template, the Jenkinsfile and the template.yaml file:

Change to the /templates directory.
Create the subfolder for the template.
Using the text editor of your choice, create an empty file.
Populate the file with the appropriate template.yaml configuration values.
Save the file as template.yaml.
Create another empty file and populate it with the appropriate Jenkinsfile configuration values.
Save the file as Jenkinsfile.
Commit the subfolder and files to the /templates directory of your source code repository.

Customizing Template parameters

Templates are customized using the optional parameters section of the template.yaml file. Parameters are defined in template.yaml, and are then used as substitution variables in the Jenkinsfile.

Each parameter is specified as a block containing a mixture of required and optional fields. These values can be customized each time a Pipeline based on a Template is updated.

The following table lists the valid options for each parameter.

Parameter Description Required?

Parameter	Description	Required?
name	The name used for the parameter in the Jenkinsfile.	Yes
displayName	The name used in the CloudBees CI user interface; shown to the developer when they are creating a new job.	Yes
allowedValues	An array containing the list of values allowed for the parameter.	No
default	The default value to be used for the parameter. If specified in the `template.yaml` file, this value will be shown pre-populated in the user interface when the developer creates a job. The developer can replace this value or choose to use the default. The default value must use the same data type of the parameter. For example, a `string` type must have a default value that is a string.	No
type	The data type for the parameter (DataType). See the types table for details on the supported type values.	Yes

name

The name used for the parameter in the Jenkinsfile.

Yes

displayName

The name used in the CloudBees CI user interface; shown to the developer when they are creating a new job.

Yes

allowedValues

An array containing the list of values allowed for the parameter.

default

The default value to be used for the parameter. If specified in the template.yaml file, this value will be shown pre-populated in the user interface when the developer creates a job. The developer can replace this value or choose to use the default. The default value must use the same data type of the parameter. For example, a string type must have a default value that is a string.

type

The data type for the parameter (DataType). See the types table for details on the supported type values.

Yes

The following table lists the valid options for the type parameter:

Type	Description	Required?
string	A literal string. For example, users could specify "SlackChannel". The string parameter also supports allowedValues for populating the ChoiceControl (radio button list) in the CloudBees CI user interface when the developer is creating the job.	No
number	An integer.	No
boolean	A control for enabling the developer to select an option. For a future templating version, we will consider adding support for a new type to enable a list of items that supports selection of multiple values. Displayed in the CloudBees CI user interface as a checkbox.	No
credentials	The ID of credentials managed by Jenkins. The GUI will display the drop down list of available credentials.	No

Type

Description

Required?

string

A literal string. For example, users could specify "SlackChannel". The string parameter also supports allowedValues for populating the ChoiceControl (radio button list) in the CloudBees CI user interface when the developer is creating the job.

number

An integer.

boolean

A control for enabling the developer to select an option. For a future templating version, we will consider adding support for a new type to enable a list of items that supports selection of multiple values. Displayed in the CloudBees CI user interface as a checkbox.

credentials

The ID of credentials managed by Jenkins. The GUI will display the drop down list of available credentials.

Example `template.yaml`

Download file from GitHub

  version: 1
  type: pipeline-template

  name: Java Maven App Pipeline Job
  description: Simple Java App With Maven
  parameters:
    - name: emailRecipient
      type: string
      displayName: Email address to be used for sending build notifications
    - name: github_repo
      type: string
      displayName: GitHub HTTPS repo endpoint
    - name: github_creds
      displayName: GitHub Credentials ID
      type: credentials
      defaultValue: github-creds-example▼

Example `Jenkinsfile`

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
              git credentialsId: "${github_creds}", url: "${github_repo}"
            }
        }
        stage('Build') {
            steps {
                sh 'mvn -B -DskipTests clean package'
            }
        }
    }

    post {

    // Email Ext plugin:
    success {

      emailext (
          subject: "SUCCESSFUL: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]'",
          body: """<p>SUCCESSFUL: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]':</p>
            <p>Check console output at &QUOT;<a href='${env.BUILD_URL}'>${env.JOB_NAME} [${env.BUILD_NUMBER}]</a>&QUOT;</p>""",
          to: "${emailRecipient}",
          from: "buildNotifications@emailaddress.com"
        )
    }

    failure {

      emailext (
          subject: "FAILED: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]'",
          body: """<p>FAILED: Job '${env.JOB_NAME} [${env.BUILD_NUMBER}]':</p>
            <p>Check console output at &QUOT;<a href='${env.BUILD_URL}'>${env.JOB_NAME} [${env.BUILD_NUMBER}]</a>&QUOT;</p>""",
          to: "${emailRecipient}",
          from: "buildNotifications@emailaddress.com"
        )
    }
  }
}▼

Setting up a Pipeline Template

Customizing Template parameters

Example template.yaml

Example Jenkinsfile

Example `template.yaml`

Example `Jenkinsfile`