Multibranch Pipeline Template syntax

This document explains how to configure various options related to Multibranch Pipelines via YAML syntax.

The starting point is the BranchSource object, so configurations always start with branchSource:.

Each object specifies what parameters it has and the type of those parameters. Some objects do not have any parameters. Some parameters are marked as optional and do not need to be specified. All non-optional parameters should be specified when configuring an object.

The following list includes the six types of parameters explained with examples:

… is used as a placeholder where additional configuration has been omitted to focus on the specific parameter type being discussed.

Simple Types (for example, Type: String, Type: int)

This parameter accepts a simple value.
```
branchSource:
  git:
    ...
    traits:
      - $class: CheckoutOptionTrait
        extension:
          timeout: 3 (1)▼
```
1 CheckoutOption’s timeout parameter accepts Type: String.
Enum Types (e.g. Values: Option1, Option2, Option3)

This parameter accepts one of the given set of values.
```
branchSource:
  ...
  strategy:
    $class: DefaultBranchPropertyStrategy
    props:
      - $class: DurabilityHintBranchProperty
        hint: PERFORMANCE_OPTIMIZED (1)▼
```
1 DurabilityHintBranchProperty’s hint parameter accepts any of Values: PERFORMANCE_OPTIMIZED, SURVIVABLE_NONATOMIC, MAX_SURVIVABILITY.

Nested $TYPE object

This parameter accepts a nested object configuration. The nested object has a specific type, so its parameters are specified without $class or a symbol.

branchSource:
  git:
    ...
    traits:
      - $class: CheckoutOptionTrait
        extension: (1)
          timeout: 3 (2)▼

1	CheckoutOption’s `extension` parameter accepts a Nested GitCheckoutOption object.
2	Only the parameters of the nested object need to be specified. There is no need to specify `$class` or a symbol.

Nested Choice of $TYPE objects

This parameter accepts a nested object configuration. The nested object may be any one out of a set of possible types, so $class or a symbol name must be specified for the type being used. The section for the parameter type in question contains a list where each item in the list starts with either the $class name or symbol name for the type. Parameters on the nested object are specified at the same level when using $class, but are nested one level deeper when using a symbol.

Example using $class

branchSource:
  ...
  strategy: (1)
    $class: DefaultBranchPropertyStrategy (2)
    props: (3)
      - $class: DurabilityHintBranchProperty
        hint: PERFORMANCE_OPTIMIZED▼

1	BranchSource’s `strategy` parameter accepts a Nested BranchProjectStrategy object.
2	We use use `$class: DefaultBranchPropertyStrategy` to indicate what option we selected. Another possible option is `$class: NamedExceptionsBranchPropertyStrategy`. All options are listed under BranchPropertyStrategy
3	DefaultBranchPropertyStrategy’s parameters are specified at the same level as `$class`.

List of Nested $TYPE object

This parameter accepts a list, where each item in the list is a nested configuration of the same type of object. Since the nested objects have a specific type, their parameters are specified without using $class or a symbol.

branchSource:
  ...
  strategy:
    $class: NamedExceptionsBranchPropertyStrategy
    namedExceptions:(1)
      - name: main(2)
        props:
          ...
      - name: stable(3)
        props:
          ...
    defaultProperties:
        ...▼

1	NamedExceptionsBranchPropertyStrategy’s `namedExceptions` parameter accepts a List of Nested Named object.
2	Only the parameters of the nested objects need to be specified. There is no need to specify `$class` or a symbol.
3	Each item in the list begins with `-`. This example shows two items in the list.

List of Nested Choice of $TYPE objects

This parameter accepts a list, where each item in the list may be any one out of a set of possible types, so $class or a symbol name must be specified for the type being used. Parameters on the nested objects are specified at the same level when using $class, but are nested one level deeper when using a symbol.

branchSource:
  git:
    ...
    traits: (1)
      - $class: CheckoutOptionTrait
        extension: (2)
          timeout: 3
      - headWildcardFilter:
          includes: ... (3)
          excludes: ...
      - $class: CleanBeforeCheckoutTrait (4)
      - gitBranchDiscovery (5)▼

1	Git’s `traits` parameter accepts a List of Nested Choice of Git-specific SCMSourceTrait objects
2	Nested objects using `$class` have their parameters at the same level as `$class`.
3	Nested objects using a symbol have their parameters nested one level deeper than the symbol.
4	Example of a nested object using `$class` that does not have any parameters of its own.
5	Example of a nested object using a symbol that does not have any parameters of its own.