Setting up a Pipeline Template

3 minute read

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:

  1. Change to the /templates directory.

  2. Create the subfolder for the template.

  3. Using the text editor of your choice, create an empty file.

  4. Populate the file with the appropriate template.yaml configuration values.

  5. Save the file as template.yaml.

  6. Create another empty file and populate it with the appropriate Jenkinsfile configuration values.

  7. Save the file as Jenkinsfile.

  8. 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?

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

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?

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

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

Example template.yaml

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" ) } } }