Multibranch Pipeline Project¶
The Multibranch Pipeline project module handles creating Jenkins workflow
projects.
You may specify multibranch
in the project-type
attribute of
the Job definition.
Multibranch Pipeline implementantion in JJB is marked as experimental which means that there is no guarantee that its behavior (or configuration) will not change, even between minor releases.
- Plugins required:
- Workflow Plugin.
- Pipeline Multibranch Defaults Plugin (optional)
- Basic Branch Build Strategies Plugin (optional)
Job Parameters: |
|
---|
Job examples:
name: 'demo-multibranch-defaults'
project-type: multibranch-defaults
scm:
- github:
repo: 'foo'
repo-owner: 'johndoe'
credentials-id: 'secret'
name: 'demo-multibranch-multi-scm-full'
description: 'Workflow demo'
project-type: multibranch
periodic-folder-trigger: 1d
prune-dead-branches: True
number-to-keep: '10'
days-to-keep: '10'
script-path: 'some.Jenkinsfile'
scm:
- bitbucket:
repo-owner: 'SANDBOX'
repo: 'test'
credentials-id: 'secret'
- git:
url: 'https://example.com/jonhndoe/keep-frontend.git'
credentials-id: 'secret'
- github:
repo: 'foo'
repo-owner: 'johndoe'
credentials-id: 'secret'
-
project_multibranch.
bitbucket_scm
(xml_parent, data)¶ Configure BitBucket scm
Requires the Bitbucket Branch Source Plugin.
Parameters: - credentials-id (str) – The credential to use to scan BitBucket. (required)
- repo-owner (str) – Specify the name of the Bitbucket Team or Bitbucket User Account. (required)
- repo (str) – The BitBucket repo. (required)
- discover-tags (bool) – Discovers tags on the repository. (default false)
- server-url (str) – The address of the bitbucket server. (optional)
- head-filter-regex (str) – A regular expression for filtering discovered source branches. Requires the SCM API Plugin.
- discover-branch (str) – Discovers branches on the repository. Valid options: ex-pr, only-pr, all. Value is not specified by default.
- discover-pr-origin (str) – Discovers pull requests where the origin repository is the same as the target repository. Valid options: mergeOnly, headOnly, mergeAndHead. Value is not specified by default.
- discover-pr-forks-strategy (str) – Fork strategy. Valid options: merge-current, current, both, false. (default ‘merge-current’)
- discover-pr-forks-trust (str) – Discovers pull requests where the origin repository is a fork of the target repository. Valid options: contributors, everyone, permission or nobody. (default ‘contributors’)
- build-strategies (list) – Provides control over whether to build a branch
(or branch like things such as change requests and tags) whenever it is
discovered initially or a change from the previous revision has been
detected. (optional)
Refer to
~build_strategies
. - property-strategies (dict) – Provides control over how to build a branch
(like to disable SCM triggering or to override the pipeline durability)
(optional)
Refer to
~property_strategies
. - local-branch (bool) – Check out to matching local branch If given, checkout the revision to build as HEAD on this branch. If selected, then the branch name is computed from the remote branch without the origin. In that case, a remote branch origin/master will be checked out to a local branch named master, and a remote branch origin/develop/new-feature will be checked out to a local branch named develop/newfeature. Requires the Git Plugin.
- checkout-over-ssh (dict) –
Checkout repo over ssh.
- credentials (‘str’): Credentials to use for
- checkout of the repo over ssh.
- filter-by-name-wildcard (dict) –
Enable filter by name with wildcards. Requires the SCM API Plugin.
- includes (‘str’): Space-separated list
- of name patterns to consider. You may use * as a wildcard; for example: master release*
- excludes (‘str’): Name patterns to
- ignore even if matched by the includes list. For example: release*
Extensions: - clean (dict)
- after (bool) - Clean the workspace after checkout
- before (bool) - Clean the workspace before checkout
- prune (bool) - Prune remote branches (default false)
- shallow-clone (bool) - Perform shallow clone (default false)
- depth (int) - Set shallow clone depth (default 1)
- do-not-fetch-tags (bool) - Perform a clone without tags
- (default false)
- submodule (dict)
- disable (bool) - By disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins to ignore submodules completely as if they didn’t exist.
- recursive (bool) - Retrieve all submodules recursively (uses ‘–recursive’ option which requires git>=1.6.5)
- tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses ‘–remote’ option which requires git>=1.8.2)
- parent-credentials (bool) - Use credentials from default remote of parent repository (default false).
- reference-repo (str) - Path of the reference repo to use during clone (optional)
- timeout (int) - Specify a timeout (in minutes) for submodules operations (default 10).
- timeout (str) - Timeout for git commands in minutes (optional)
- use-author (bool): Use author rather than committer in Jenkin’s
- build changeset (default false)
- wipe-workspace (bool) - Wipe out workspace before build
- (default true)
Minimal Example:
name: 'demo-multibranch-bitbucket-min' project-type: multibranch scm: - bitbucket: repo-owner: 'SANDBOX' repo: 'test'
Full Example:
name: 'demo-multibranch-bitbucket-min' project-type: multibranch script-path: 'some.Jenkinsfile' scm: - bitbucket: credentials-id: 'secret' repo-owner: 'SANDBOX' repo: 'test' server-url: https://bitbucket.example.com:8080 discover-tags: true head-filter-regex: 'master|\d+\.\d+' discover-pr-origin: headOnly discover-branch: all discover-pr-forks-strategy: current discover-pr-forks-trust: everyone local-branch: true checkout-over-ssh: credentials: 'ssh_secret' filter-by-name-wildcard: includes: '*' excludes: 'master' property-strategies: all-branches: - suppress-scm-triggering: true - pipeline-branch-durability-override: max-survivability build-strategies: - tags: ignore-tags-newer-than: 1 ignore-tags-older-than: 7 - tags: {} - change-request: ignore-target-only-changes: true - change-request: {} - regular-branches: true - skip-initial-build: true - named-branches: - exact-name: name: 'test' case-sensitive: true - regex-name: regex: 'test.*$' case-sensitive: true - wildcards-name: excludes: 'testexclude' includes: 'testinclude' - named-branches: - exact-name: {} - regex-name: {} - wildcards-name: {} clean: after: true before: true prune: true shallow-clone: true depth: 3 do-not-fetch-tags: true submodule: disable: false recursive: true parent-credentials: true timeout: 100 timeout: "100" use-author: true wipe-workspace: true
-
project_multibranch.
build_strategies
(xml_parent, data)¶ Configure Basic Branch Build Strategies.
Requires the Basic Branch Build Strategies Plugin.
Parameters: build-strategies (list) – Definition of build strategies.
- tags (dict): Builds tags
- ignore-tags-newer-than (int) The number of days since the tag
- was created before it is eligible for automatic building. (optional, default -1)
- ignore-tags-older-than (int) The number of days since the tag
- was created after which it is no longer eligible for automatic building. (optional, default -1)
- change-request (dict): Builds change requests / pull requests
- ignore-target-only-changes (bool) Ignore rebuilding merge
- branches when only the target branch changed. (optional, default false)
- regular-branches (bool): Builds regular branches whenever a
- change is detected. (optional, default None)
- skip-initial-build (bool): Skip initial build on first branch
- indexing. (optional, default None)
- named-branches (list): Builds named branches whenever a change
is detected.
- exact-name (dict) Matches the name verbatim.
- name (str) The name to match. (optional)
- case-sensitive (bool) Check this box if the name should
- be matched case sensitively. (default false)
- regex-name (dict) Matches the name against a regular
expression.
- regex (str) A Java regular expression to restrict the
- names. Names that do not match the supplied regular expression will be ignored. (default ^.*$)
- case-sensitive (bool) Check this box if the name should
- be matched case sensitively. (default false)
- wildcards-name (dict) Matches the name against an
include/exclude set of wildcards.
- includes (str) Space-separated list of name patterns to
- consider. You may use * as a wildcard; for example: master release* (default *)
- excludes (str) Name patterns to ignore even if matched
- by the includes list. For example: release (optional)
-
project_multibranch.
gerrit_scm
(xml_parent, data)¶ Configure Gerrit SCM
Requires the Gerrit Code Review Plugin.
Parameters: - url (str) – The git url. (required)
- credentials-id (str) – The credential to use to connect to the GIT URL.
- ignore-on-push-notifications (bool) – If a job should not trigger upon push notifications. (default false)
- refspecs (list(str)) – Which refspecs to look for.
(default
['+refs/changes/*:refs/remotes/@{remote}/*', '+refs/heads/*:refs/remotes/@{remote}/*']
) - includes (str) – Comma-separated list of branches to be included. (default ‘*’)
- excludes (str) – Comma-separated list of branches to be excluded. (default ‘’)
- build-strategies (list) – Provides control over whether to build a branch
(or branch like things such as change requests and tags) whenever it is
discovered initially or a change from the previous revision has been
detected. (optional)
Refer to
~build_strategies
. - property-strategies (dict) – Provides control over how to build a branch
(like to disable SCM triggering or to override the pipeline durability)
(optional)
Refer to
~property_strategies
.
Minimal Example:
name: 'demo-multibranch-gerrit-min' project-type: multibranch scm: - gerrit: url: 'https://review.gerrithub.io/johndoe/foo'
Full Example:
name: 'demo-multibranch-gerrit-min' project-type: multibranch script-path: some.Jenkinsfile scm: - gerrit: url: 'https://review.gerrithub.io/johndoe/foo' credentials-id: secret ignore-on-push-notifications: true refspecs: 'refs/heads/*' property-strategies: all-branches: - suppress-scm-triggering: true - pipeline-branch-durability-override: max-survivability build-strategies: - tags: ignore-tags-newer-than: 1 ignore-tags-older-than: 7 - tags: {} - change-request: ignore-target-only-changes: true - change-request: {} - regular-branches: true - skip-initial-build: true - named-branches: - exact-name: name: 'test' case-sensitive: true - regex-name: regex: 'test.*$' case-sensitive: true - wildcards-name: excludes: 'testexclude' includes: 'testinclude' - named-branches: - exact-name: {} - regex-name: {} - wildcards-name: {}
-
project_multibranch.
git_scm
(xml_parent, data)¶ Configure Git SCM
Requires the Git Plugin.
Parameters: - url (str) – The git repo url. (required)
- credentials-id (str) – The credential to use to connect to the GIT repo. (default ‘’)
- discover-branches (bool) – Discovers branches on the repository. (default true)
- discover-tags (bool) – Discovers tags on the repository. (default false)
- ignore-on-push-notifications (bool) – If a job should not trigger upon push notifications. (default false)
- head-filter-regex (str) – A regular expression for filtering discovered source branches. Requires the SCM API Plugin.
- build-strategies (list) – Provides control over whether to build a branch
(or branch like things such as change requests and tags) whenever it is
discovered initially or a change from the previous revision has been
detected. (optional)
Refer to
~build_strategies
. - property-strategies (dict) – Provides control over how to build a branch
(like to disable SCM triggering or to override the pipeline durability)
(optional)
Refer to
~property_strategies
.
Extensions: - clean (dict)
- after (bool) - Clean the workspace after checkout
- before (bool) - Clean the workspace before checkout
- prune (bool) - Prune remote branches (default false)
- shallow-clone (bool) - Perform shallow clone (default false)
- depth (int) - Set shallow clone depth (default 1)
- do-not-fetch-tags (bool) - Perform a clone without tags
- (default false)
- submodule (dict)
- disable (bool) - By disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins to ignore submodules completely as if they didn’t exist.
- recursive (bool) - Retrieve all submodules recursively (uses ‘–recursive’ option which requires git>=1.6.5)
- tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses ‘–remote’ option which requires git>=1.8.2)
- parent-credentials (bool) - Use credentials from default remote of parent repository (default false).
- reference-repo (str) - Path of the reference repo to use during clone (optional)
- timeout (int) - Specify a timeout (in minutes) for submodules operations (default 10).
- timeout (str) - Timeout for git commands in minutes (optional)
- use-author (bool): Use author rather than committer in Jenkin’s
- build changeset (default false)
- wipe-workspace (bool) - Wipe out workspace before build
- (default true)
Minimal Example:
name: 'demo-multibranch-git-min' project-type: multibranch scm: - git: url: 'https://example.com/jonhndoe/keep-frontend.git'
Full Example:
name: 'demo-multibranch-git-min' project-type: multibranch script-path: some.Jenkinsfile scm: - git: url: 'https://example.com/jonhndoe/keep-frontend.git' credentials-id: secret discover-branches: false ignore-on-push-notifications: true discover-tags: true head-filter-regex: 'master|\d+\.\d+' property-strategies: all-branches: - suppress-scm-triggering: true - pipeline-branch-durability-override: max-survivability build-strategies: - tags: ignore-tags-newer-than: 1 ignore-tags-older-than: 7 - tags: {} - change-request: ignore-target-only-changes: true - change-request: {} - regular-branches: true - skip-initial-build: true - named-branches: - exact-name: name: 'test' case-sensitive: true - regex-name: regex: 'test.*$' case-sensitive: true - wildcards-name: excludes: 'testexclude' includes: 'testinclude' - named-branches: - exact-name: {} - regex-name: {} - wildcards-name: {} clean: after: true before: true prune: true shallow-clone: true depth: 3 do-not-fetch-tags: true submodule: disable: false recursive: true parent-credentials: true timeout: 100 timeout: "100" use-author: true wipe-workspace: true
-
project_multibranch.
github_scm
(xml_parent, data)¶ Configure GitHub SCM
Requires the GitHub Branch Source Plugin.
Parameters: - api-uri (str) – The GitHub API uri for hosted / on-site GitHub. Must first be configured in Global Configuration. (default GitHub)
- ssh-checkout (bool) –
Checkout over SSH.
- credentials (‘str’): Credentials to use for
- checkout of the repo over ssh.
- credentials-id (str) – Credentials used to scan branches and pull requests, check out sources and mark commit statuses. (optional)
- repo-owner (str) – Specify the name of the GitHub Organization or GitHub User Account. (required)
- repo (str) – The GitHub repo. (required)
- branch-discovery (str) – Discovers branches on the repository. Valid options: no-pr, only-pr, all, false. (default ‘no-pr’)
- discover-pr-forks-strategy (str) – Fork strategy. Valid options: merge-current, current, both, false. (default ‘merge-current’)
- discover-pr-forks-trust (str) – Discovers pull requests where the origin repository is a fork of the target repository. Valid options: contributors, everyone, permission or nobody. (default ‘contributors’)
- discover-pr-origin (str) – Discovers pull requests where the origin repository is the same as the target repository. Valid options: merge-current, current, both. (default ‘merge-current’)
- discover-tags (bool) – Discovers tags on the repository. (default false)
- build-strategies (list) – Provides control over whether to build a branch
(or branch like things such as change requests and tags) whenever it is
discovered initially or a change from the previous revision has been
detected. (optional)
Refer to
~build_strategies
. - notification-context (str) – Change the default GitHub check notification context from “continuous-integration/jenkins/SUFFIX” to a custom text, Requires the Github Custom Notification Context SCM Behaviour.
- property-strategies (dict) – Provides control over how to build a branch
(like to disable SCM triggering or to override the pipeline durability)
(optional)
Refer to
~property_strategies
.
Extensions: - clean (dict)
- after (bool) - Clean the workspace after checkout
- before (bool) - Clean the workspace before checkout
- prune (bool) - Prune remote branches (default false)
- shallow-clone (bool) - Perform shallow clone (default false)
- depth (int) - Set shallow clone depth (default 1)
- do-not-fetch-tags (bool) - Perform a clone without tags
- (default false)
- disable-pr-notifications (bool) - Disable default github status
- notifications on pull requests (default false) (Requires the GitHub Branch Source Plugin.)
- submodule (dict)
- disable (bool) - By disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins to ignore submodules completely as if they didn’t exist.
- recursive (bool) - Retrieve all submodules recursively (uses ‘–recursive’ option which requires git>=1.6.5)
- tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses ‘–remote’ option which requires git>=1.8.2)
- parent-credentials (bool) - Use credentials from default remote of parent repository (default false).
- reference-repo (str) - Path of the reference repo to use during clone (optional)
- timeout (int) - Specify a timeout (in minutes) for submodules operations (default 10).
- timeout (str) - Timeout for git commands in minutes (optional)
- use-author (bool): Use author rather than committer in Jenkin’s
- build changeset (default false)
- wipe-workspace (bool) - Wipe out workspace before build
- (default true)
Minimal Example:
name: 'demo-multibranch-github-min' project-type: multibranch scm: - github: repo: 'foo' repo-owner: 'johndoe'
Full Example:
name: scm-github-full project-type: multibranch script-path: some.Jenkinsfile scm: - github: api-uri: http://example.org/github ssh-checkout: credentials: 'ssh_secret' repo: example-repo repo-owner: example-owner credentials-id: example-credential branch-discovery: all head-filter-regex: "(.*/master|.*/release/.*)" discover-pr-forks-strategy: both discover-pr-forks-trust: everyone discover-pr-origin: both discover-tags: true notification-context: 'jenkins.example.com/my_context' property-strategies: all-branches: - suppress-scm-triggering: true - pipeline-branch-durability-override: max-survivability build-strategies: - tags: ignore-tags-newer-than: 1 ignore-tags-older-than: 7 - tags: {} - change-request: ignore-target-only-changes: true - change-request: {} - regular-branches: true - skip-initial-build: true - named-branches: - exact-name: name: 'test' case-sensitive: true - regex-name: regex: 'test.*$' case-sensitive: true - wildcards-name: excludes: 'testexclude' includes: 'testinclude' - named-branches: - exact-name: {} - regex-name: {} - wildcards-name: {} clean: after: true before: true prune: true shallow-clone: true depth: 3 do-not-fetch-tags: true disable-pr-notifications: true submodule: disable: false recursive: true parent-credentials: true timeout: 100 timeout: "100" use-author: true wipe-workspace: true
-
project_multibranch.
property_strategies
(xml_parent, data)¶ Configure Basic Branch Property Strategies.
Requires the Branch API Plugin.
Parameters: property-strategies (dict) – Definition of property strategies. Either named-branches or all-branches may be specified, but not both.
- all-branches (list): A list of property strategy definitions
- for use with all branches.
- suppress-scm-triggering (bool): Suppresses automatic SCM
- triggering (optional)
- pipeline-branch-durability-override (str): Set a custom
- branch speed/durability level. Valid values: performance-optimized, survivable-nonatomic, or max-survivability (optional) Requires the :jenkins-wiki: Pipeline Multibranch Plugin <Pipeline+Multibranch+Plugin>
- named-branches (dict): Named branches get different properties.
- Comprised of a list of defaults and a list of property strategy
exceptions for use with specific branches.
- defaults (list): A list of property strategy definitions
- to be applied by default to all branches, unless overridden
by an entry in exceptions
- suppress-scm-triggering (bool): Suppresses automatic SCM
- triggering (optional)
- pipeline-branch-durability-override (str): Set a custom
- branch speed/durability level. Valid values: performance-optimized, survivable-nonatomic, or max-survivability (optional) Requires the :jenkins-wiki: Pipeline Multibranch Plugin <Pipeline+Multibranch+Plugin>
- exceptions (list): A list of branch names and the property
- strategies to be used on that branch, instead of any listed
in defaults.
- exception (dict): Defines exception
- branch-name (str): Name of the branch to which these
- properties will be applied.
- properties (list): A list of properties to apply to
- this branch.
- suppress-scm-triggering (bool): Suppresses
- automatic SCM triggering (optional)
- pipeline-branch-durability-override (str): Set a
- custom branch speed/durability level. Valid values: performance-optimized, survivable-nonatomic, or max-survivability (optional) Requires the Pipeline Multibranch Plugin