Setting up a Pipeline Template

Pipeline Templates are stored under the /templates folder within the source code repository containing a Pipeline Template Catalog, 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.

The `template.yaml` file

The table below provides the details of the different properties that can be set in the template.yaml file.

Field Description Required?

Field	Description	Required?
description	A longer description of the template.	No
displayName	The name to be shown in the CloudBees CI user interface.	Yes
name	The name of the template.	Yes
multibranch	Field to describe specific multibranch configurations. Refer to the Managing Multibranch Pipeline options in `template.yaml` section for more information.	Required for templates with the `MULTIBRANCH` value in the `templateType` property.
parameters	A list of parameters that can be customized when the template is used to create a new job. Refer to the Parameter types in `template.yaml` section for more information.	No
templateFile	The name of the file in the `templates/TEMPLATE_NAME` directory that contains the Pipeline template script contents. Defaults to `Jenkinsfile`.	No
templateType	The type of template. Values can be SCRIPTED` or `MULTIBRANCH`. Defaults to `SCRIPTED`.	Required for multibranch templates.
type	The only valid value is `pipeline-template`.	Yes
version	`template.yaml` version. The only valid value is `1`.	No

description

A longer description of the template.

displayName

The name to be shown in the CloudBees CI user interface.

Yes

name

The name of the template.

Yes

multibranch

Field to describe specific multibranch configurations. Refer to the Managing Multibranch Pipeline options in template.yaml section for more information.

Required for templates with the MULTIBRANCH value in the templateType property.

parameters

A list of parameters that can be customized when the template is used to create a new job. Refer to the Parameter types in template.yaml section for more information.

templateFile

The name of the file in the templates/TEMPLATE_NAME directory that contains the Pipeline template script contents. Defaults to Jenkinsfile.

templateType

The type of template. Values can be SCRIPTED` or MULTIBRANCH. Defaults to SCRIPTED.

Required for multibranch templates.

type

The only valid value is pipeline-template.

Yes

version

template.yaml version. The only valid value is 1.

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

The template.yaml file

Customizing Template parameters

Example template.yaml

Example Jenkinsfile

The `template.yaml` file

Example `template.yaml`

Example `Jenkinsfile`