BranchPropertyStrategy objects

3 minute read
The starting point is the BranchSource object, so configurations always start with branchSource:.
For more information on how to configure various options related to Multibranch Pipelines via YAML syntax, see Mutibranch Pipeline Template yaml syntax guide.

BranchProperty objects

  • $class: 'DurabilityHintBranchProperty'

    This setting allows users to change the default durability mode for running Pipelines. In most cases this is a trade-off between performance and the ability for running pipelines to resume after unplanned Jenkins outages.

    What does this do?

    Previously, running pipelines wrote data constantly, so that they could resume even if Jenkins fails. This setting gives the user the ability to adjust this write behavior. Higher-performance/lower-durability modes write data to disk much less often for running pipelines. Writing data less often can massively reduce build times for Pipelines with many steps or complex logic. For pipelines which spend most of their time waiting for a shell/batch script to run, the difference will be less visible.

    Running pipelines with lower durability settings may lose data if they do not finish and Jenkins is not shut down gracefully. A "graceful" shutdown is where Jenkins goes through a full shutdown process, such as visiting http://[jenkins-server]/exit. A "dirty" shutdown, such as using kill -9 to terminate the Jenkins process, may prevent incomplete pipelines from persisting data. Pipelines that cannot persist data may not be able to resume or displayed in Blue Ocean/Stage View/etc.

    Pipelines will generally write log data regardless of durability settings. Some modes use an "atomic write" option - this helps ensure that pipeline build files aren’t overwritten or left partially written if something fails. Atomic writes may place more stress on filesystems, so especially with networked storage it may be faster not to use them.

    Defaults may be set globally under Manage Jenkins > Configure System.
    Table 3. DurabilityHintBranchProperty parameters
    Parameter Type Description

    hint

    Values: PERFORMANCE_OPTIMIZED, SURVIVABLE_NONATOMIC, MAX_SURVIVABILITY

  • $class: 'NoTriggerBranchProperty'

    This setting suppresses the build trigger coming from branch indexing or normal SCM commit events.

    Table 4. NoTriggerBranchProperty parameters
    Parameter Type Description

    suppressAutomaticTriggering

    Values: EVENTS, INDEXING, NONE

Named object

Named exception

Table 5. Named object parameters
Parameter Type Description

name

String

The name of the branch that this exception applies to. Name matching is case insensitive. This name can be a comma separated list of names. The name can include Ant style wildcards. Prefixing a name with ! will invert the match. (If you have an actual branch name that starts with ! or \! you will need to escape it with a leading \. The escape only applies to the first character of the name.)

Some examples:

  • production matches one and only one branch

  • sandbox/* will match sandbox/acme but not sandbox/coyote/wiley

  • sandbox/** will match sandbox/acme and sandbox/coyote/wiley

  • production,staging matches two specific branches

  • production,staging* matches the production branch and any branch starting with staging

  • !staging/**,staging/test/** matches any branch that is not a staging branch, but will match the staging/test branches

  • \!starts-with-invert matches the branch with the name !starts-with-invert

  • \\!starts-with-escape matches the branch with the name \!starts-with-escape

  • \escape-only-for-invert matches the branch with the name \escape-only-for-invert

  • no-internal-!-escape matches the branch with the name no-internal-!-escape

  • no-internal-\-escape matches the branch with the name no-internal-\-escape

props

List of Nested Choice of BranchProperty objects