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:
Pipeline Multibranch Defaults Plugin (optional)
Basic Branch Build Strategies Plugin (optional)
- Job Parameters:
scm (list): The SCM definition.
bitbucket (dict): Refer to
~bitbucket_scm
for documentation.gerrit (dict): Refer to
~gerrit_scm
for documentation.git (dict): Refer to
~git_scm
for documentation.github (dict): Refer to
~github_scm
for documentation.
periodic-folder-trigger (str): How often to scan for new branches or pull/change requests. Valid values: 1m, 2m, 5m, 10m, 15m, 20m, 25m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 2d, 1w, 2w, 4w. (default none)
prune-dead-branches (bool): If dead branches upon check should result in their job being dropped. (default true)
number-to-keep (int): How many builds should be kept. (default ‘-1, all’)
days-to-keep (int): For how many days should a build be kept. (default ‘-1, forever’)
abort-builds (bool): Abort all pending or ongoing builds for removed SCM heads (i.e. deleted branches). (default false)
script-path (str): Path to Jenkinsfile, relative to workspace. (default ‘Jenkinsfile’)
script-id (str): Script id from the global Jenkins script store provided by the config-file provider plugin. Mutually exclusive with script-path option.
sandbox (bool): This option is strongly recommended if the Jenkinsfile is using load to evaluate a groovy source file from an SCM repository. Usable only with script-id option. (default ‘false’)
Job examples:
name: 'demo-multibranch-defaults'
project-type: multibranch-defaults
script-id: my-pipeline
sandbox: true
scm:
- github:
repo: 'foo'
repo-owner: 'johndoe'
credentials-id: 'secret'
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'
abort-builds: True
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'
- class project_multibranch.WorkflowMultiBranch(registry)¶
- sequence = 0¶
The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
- class project_multibranch.WorkflowMultiBranchDefaults(registry)¶
- project_multibranch.add_filter_branch_pr_behaviors(traits, data)¶
Configure Filter Branch PR behaviors
Requires the SCM Filter Branch PR Plugin.
- Parameters:
head-pr-filter-behaviors (list) –
Definition of filters.
- head-pr-destined-regex (dict): Filter by name incl. PR destined to
this branch with regexp
- branch-regexp (str) Regular expression to filter branches and
PRs (optional, default “.*”)
- tag-regexp (str) Regular expression to filter tags
(optional, default “(?!.*)”)
- head-pr-destined-wildcard (dict): Filter by name incl. PR
destined to this branch with wildcard
- branch-includes (str) Wildcard expression to include branches
and PRs (optional, default “*”)
- tag-includes (str) Wildcard expression to include tags
(optional, default “”)
- branch-excludes (str) Wildcard expression to exclude branches
and PRs (optional, default “”)
- tag-excludes (str) Wildcard expression to exclude tags
(optional, default “*”)
- head-pr-originated-regex (dict): Filter by name incl. PR destined
to this branch with regexp
- branch-regexp (str) Regular expression to filter branches
and PRs (optional, default “.*”)
- tag-regexp (str) Regular expression to filter tags
(optional, default “(?!.*)”)
- head-pr-originated-wildcard (dict): Filter by name incl. PR
destined to this branch with wildcard
- branch-includes (str) Wildcard expression to include branches
and PRs (optional, default “*”)
- tag-includes (str) Wildcard expression to include tags
(optional, default “”)
- branch-excludes (str) Wildcard expression to exclude branches
and PRs (optional, default “”)
- tag-excludes (str) Wildcard expression to exclude tags
(optional, default “*”)
- project_multibranch.add_filter_by_name_wildcard_behaviors(traits, data)¶
Configure branch filtering behaviors.
- Parameters:
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*
- project_multibranch.add_github_checks_traits(traits, data)¶
Enable and configure the usage of GitHub Checks API
Requires the Github Checks plugin.
- Parameters:
status-checks (dict) –
name (str): The text of the context label for GitHub Checks entry
skip (bool): Skips publishing Checks (optional, default false)
- skip-branch-source-notifications (bool): Disables the default
option of publishing statuses through Status API (optional, default false)
- publish-unstable-as-neutral (bool): Publishes UNSTABLE builds
as neutral (not failed) checks (optional, default false)
- suppress-log-output (bool): Suppresses sending build logs to GitHub
(optional, default false)
- suppress-progress-updates (bool): Suppresses updating build progress
(optional, default false)
- verbose-logs (bool): Enables sending build console logs to GitHub
(optional, default false)
- project_multibranch.add_notification_context_trait(traits, data)¶
Change the default GitHub check notification context from “continuous-integration/jenkins/SUFFIX” to a custom label / suffix. (set a label and suffix to true or false, optional)
Requires the Github Custom Notification Context SCM Behaviour.
- Parameters:
notification-context (dict) –
Definition of notification-context. A label must be specified. suffix may be specified with true / false, default being true.
- label (str): The text of the context label for Github status
notifications.
- suffix (bool): Appends the relevant suffix to the context label
based on the build type. ‘/pr-merge’, ‘/pr-head’ or ‘/branch’ (optional, default true)
- 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)
lfs (bool) – Git LFS pull after checkout. (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.
head-pr-filter-behaviors (list) – Definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin. Refer to
~add_filter_branch_pr_behaviors
.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.
refspecs (list(str)) – Which refspecs to look for.
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 (dict) - Clean the workspace after checkout
remove-stale-nested-repos (bool) - Deletes untracked submodules and any other subdirectories which contain .git directories (default false)
- before (dict) - Clean the workspace before checkout
remove-stale-nested-repos (bool) - Deletes untracked submodules and any other subdirectories which contain .git directories (default false)
prune (bool) - Prune remote branches (default false)
shallow-clone (bool) - Perform shallow clone (default false)
- sparse-checkout (dict)
paths (list) - List of paths to sparse checkout. (optional)
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)
- lfs-pull (bool) - Call git lfs pull after checkout
(default false)
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 lfs: true head-filter-regex: 'master|\d+\.\d+' head-pr-filter-behaviors: head-pr-destined-regex: branch-regexp: "foo/.*" tag-regexp: "20\\..*" head-pr-destined-wildcard: branch-includes: "foo*" tag-includes: "qaz*" branch-excludes: "bar*" tag-excludes: "*baz" head-pr-originated-regex: branch-regexp: "(foo/.*|bar/.*)" tag-regexp: "1\\..*" head-pr-originated-wildcard: branch-includes: "qaz*" tag-includes: "bar*" branch-excludes: "baz*" tag-excludes: "*qaz" 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 refspecs: - '+refs/heads/*:refs/remotes/@{remote}/*' - '+refs/tags/*:refs/remotes/@{remote}/*' build-strategies: - all-strategies-match: strategies: - regular-branches: true - skip-initial-build: true - any-strategies-match: strategies: - change-request: {} - tags: {} - 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 committer: user: CI System email: no-reply@ci.example.com prune: true sparse-checkout: paths: - "path1" - "path2" - "path3" shallow-clone: true depth: 3 do-not-fetch-tags: true submodule: disable: false recursive: true parent-credentials: true timeout: 100 threads: 1 timeout: "100" skip-notifications: true use-author: true wipe-workspace: true lfs-pull: true
- project_multibranch.build_strategies(xml_parent, data)¶
Configure Basic Branch Build Strategies.
Requires the Basic Branch Build Strategies Plugin.
Other build strategies can be configured via raw XML injection.
- Parameters:
build-strategies (list) –
Definition of build strategies.
- all-strategies-match (dict): All sub strategies must match for
this strategy to match. * strategies (list): Sub strategies
- any-strategies-match (dict): Builds whenever any of the sub
strategies match. * strategies (list): Sub 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)
- raw (dict): Injects raw BuildStrategy XML to use other build
strategy plugins.
- 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 ‘’)
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
.filter-checks (dict) – Enable the filtering by pending checks, allowing to discover the changes that need validation only. This feature is using the gerrit checks plugin. (optional) query-operator: Name of the query operator, supported values are: ‘SCHEME’ or ‘ID’. query-string: Value of the query operator.
change-discovery (dict) – Configure the query string in ‘Discover open changes’. The default ‘p:<project> status:open -age:24w’ will be added prior to the query-string specified here. (optional) query-string: Value of the query operator.
- Extensions:
- clean (dict)
- after (dict) - Clean the workspace after checkout
remove-stale-nested-repos (bool) - Deletes untracked submodules and any other subdirectories which contain .git directories (default false)
- before (dict) - Clean the workspace before checkout
remove-stale-nested-repos (bool) - Deletes untracked submodules and any other subdirectories which contain .git directories (default false)
prune (bool) - Prune remote branches (default false)
shallow-clone (bool) - Perform shallow clone (default false)
- sparse-checkout (dict)
paths (list) - List of paths to sparse checkout. (optional)
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)
- lfs-pull (bool) - Call git lfs pull after checkout
(default false)
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 filter-checks: query-operator: 'SCHEME' query-string: 'jenkins' build-strategies: - all-strategies-match: strategies: - regular-branches: true - skip-initial-build: true - any-strategies-match: strategies: - change-request: {} - tags: {} - 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: {} head-filter-regex: "(.*/master|.*/release/.*)" clean: after: true before: true prune: true local-branch: true sparse-checkout: paths: - "path1" - "path2" - "path3" shallow-clone: true depth: 3 do-not-fetch-tags: true submodule: disable: false recursive: true parent-credentials: true timeout: 100 threads: 1 timeout: "100" use-author: true wipe-workspace: true lfs-pull: true
- 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.
head-pr-filter-behaviors (list) – Definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin. Refer to
~add_filter_branch_pr_behaviors
.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 (dict) - Clean the workspace after checkout
remove-stale-nested-repos (bool) - Deletes untracked submodules and any other subdirectories which contain .git directories (default false)
- before (dict) - Clean the workspace before checkout
remove-stale-nested-repos (bool) - Deletes untracked submodules and any other subdirectories which contain .git directories (default false)
prune (bool) - Prune remote branches (default false)
shallow-clone (bool) - Perform shallow clone (default false)
- sparse-checkout (dict)
paths (list) - List of paths to sparse checkout. (optional)
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)
- lfs-pull (bool) - Call git lfs pull after checkout
(default false)
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+' head-pr-filter-behaviors: head-pr-destined-regex: branch-regexp: "foo/.*" tag-regexp: "20\\..*" head-pr-destined-wildcard: branch-includes: "foo*" tag-includes: "qaz*" branch-excludes: "bar*" tag-excludes: "*baz" head-pr-originated-regex: branch-regexp: "(foo/.*|bar/.*)" tag-regexp: "1\\..*" head-pr-originated-wildcard: branch-includes: "qaz*" tag-includes: "bar*" branch-excludes: "baz*" tag-excludes: "*qaz" property-strategies: all-branches: - suppress-scm-triggering: true - pipeline-branch-durability-override: max-survivability build-strategies: - all-strategies-match: strategies: - regular-branches: true - skip-initial-build: true - any-strategies-match: strategies: - change-request: {} - tags: {} - 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: {} - raw: xml: | <com.igalg.jenkins.plugins.multibranch.buildstrategy.IncludeRegionBranchBuildStrategy plugin="multibranch-build-strategy-extension"> <includedRegions>my/cool/project/*.cpp</includedRegions> </com.igalg.jenkins.plugins.multibranch.buildstrategy.IncludeRegionBranchBuildStrategy> clean: after: true before: true prune: true local-branch: true sparse-checkout: paths: - "path1" - "path2" - "path3" shallow-clone: true depth: 3 do-not-fetch-tags: true submodule: disable: false recursive: true parent-credentials: true timeout: 100 threads: 1 timeout: "100" use-author: true wipe-workspace: true lfs-pull: 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, false. (default ‘merge-current’)
discover-tags (bool) – Discovers tags on the repository. (default false)
head-pr-filter-behaviors (list) – Definition of Filter Branch PR behaviors. Requires the SCM Filter Branch PR Plugin. Refer to
~add_filter_branch_pr_behaviors
.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 (dict) – Change the default GitHub check notification context from “continuous-integration/jenkins/SUFFIX” to a custom label / suffix. (set a label and suffix to true or false, optional) Requires the Github Custom Notification Context SCM Behaviour. Refer to
~add_notification_context_trait
.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
.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 (dict) - Clean the workspace after checkout
- remove-stale-nested-repos (bool) - Deletes untracked
submodules and any other subdirectories which contain .git directories (default false)
- before (dict) - Clean the workspace before checkout
- remove-stale-nested-repos (bool) - Deletes untracked
submodules and any other subdirectories which contain .git directories (default false)
prune (bool) - Prune remote branches (default false)
shallow-clone (bool) - Perform shallow clone (default false)
- sparse-checkout (dict)
paths (list) - List of paths to sparse checkout. (optional)
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.)
refspecs (list(str)): Which refspecs to fetch.
- 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)
- lfs-pull (bool) - Call git lfs pull after checkout
(default false)
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/.*)" head-pr-filter-behaviors: head-pr-destined-regex: branch-regexp: "foo/.*" tag-regexp: "20\\..*" head-pr-destined-wildcard: branch-includes: "foo*" tag-includes: "qaz*" branch-excludes: "bar*" tag-excludes: "*baz" head-pr-originated-regex: branch-regexp: "(foo/.*|bar/.*)" tag-regexp: "1\\..*" head-pr-originated-wildcard: branch-includes: "qaz*" tag-includes: "bar*" branch-excludes: "baz*" tag-excludes: "*qaz" discover-pr-forks-strategy: both discover-pr-forks-trust: everyone discover-pr-origin: both discover-tags: true notification-context: label: 'jenkins.example.com/my_context' suffix: false status-checks: name: my-checks skip: true skip-branch-source-notifications: true publish-unstable-as-neutral: true suppress-log-output: true suppress-progress-updates: true verbose-logs: true property-strategies: all-branches: - suppress-scm-triggering: suppression-strategy: suppress-branch-indexing branch-regex: ^.*test.*$ - pipeline-branch-durability-override: max-survivability - trigger-build-on-pr-comment: comment: "Ci build!" allow-untrusted-users: true - trigger-build-on-pr-review: allow-untrusted-users: true - trigger-build-on-pr-update: allow-untrusted-users: true build-strategies: - all-strategies-match: strategies: - regular-branches: true - skip-initial-build: true - any-strategies-match: strategies: - change-request: {} - tags: {} - 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 committer: user: CI System email: no-reply@ci.example.com prune: true local-branch: true sparse-checkout: paths: - "path1" - "path2" - "path3" shallow-clone: true depth: 3 do-not-fetch-tags: true disable-pr-notifications: true refspecs: - '+refs/heads/*:refs/remotes/@{remote}/*' submodule: disable: false recursive: true parent-credentials: true timeout: 100 threads: 1 timeout: "100" skip-notifications: true use-author: true wipe-workspace: true lfs-pull: 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 (dict):
Suppresses automatic SCM triggering (optional).
- branch-regex (str):
Regex matching branch names. Only these branches will be affected by the selected suppression strategy. Default
^$
.
- suppress-strategy (str):
Select what to suppress for branches matching the regex. Valid values:
suppress-nothing
(default),suppress-branch-indexing
, orsuppress-webhooks
.Note
Using
suppress-scm-triggering: true
is deprecated since Branch API 2.1045.v4ec3ed07b_e4f.
- 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
- trigger-build-on-pr-comment (str or dict): The comment body to
trigger a new build for a PR job when it is received. This is compiled as a case-insensitive regular expression, so use
".*"
to trigger a build on any comment whatsoever. (optional) If dictionary syntax is used, the option requires 2 fields:comment
with the comment body andallow-untrusted-users
(bool) causing the plugin to skip checking if the comment author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin
- trigger-build-on-pr-review (bool or dict): This property will
cause a job for a pull request
(PR-*)
to be triggered immediately when a review is made on the PR in GitHub. This has no effect on jobs that are not for pull requests. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users
(bool) causing the plugin to skip checking if the review author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin
- trigger-build-on-pr-update (bool or dict): This property will
cause a job for a pull request
(PR-*)
to be triggered immediately when the PR title or description is edited in GitHub. This has no effect on jobs that are not for pull requests. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users
(bool) causing the plugin to skip checking if the update author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build 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 (dict):
Suppresses automatic SCM triggering (optional).
- branch-regex (str):
Regex matching branch names. Only these branches will be affected by the selected suppression strategy. Default
^$
.
- suppress-strategy (str):
Select what to suppress for branches matching the regex. Valid values:
suppress-nothing
(default),suppress-branch-indexing
, orsuppress-webhooks
.Note
Using
suppress-scm-triggering: true
is deprecated since Branch API 2.1045.v4ec3ed07b_e4f.
- 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
- trigger-build-on-pr-comment (str or dict): The comment body to
trigger a new build for a PR job when it is received. This is compiled as a case-insensitive regular expression, so use
".*"
to trigger a build on any comment whatsoever. (optional) If dictionary syntax is used, the option accepts 2 fields:comment
(str, required) with the comment body andallow-untrusted-users
(bool, optional) causing the plugin to skip checking if the comment author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin
- trigger-build-on-pr-review (bool or dict): This property will
cause a job for a pull request
(PR-*)
to be triggered immediately when a review is made on the PR in GitHub. This has no effect on jobs that are not for pull requests. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users
(bool) causing the plugin to skip checking if the review author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build Plugin
- trigger-build-on-pr-update (bool or dict): This property will
cause a job for a pull request
(PR-*)
to be triggered immediately when the PR title or description is edited in GitHub. This has no effect on jobs that are not for pull requests. (optional) If dictionary syntax is used, the option requiresallow-untrusted-users
(bool) causing the plugin to skip checking if the update author is a collaborator of the GitHub project. Requires the GitHub PR Comment Build 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 (dict):
Suppresses automatic SCM triggering (optional).
- branch-regex (str):
Regex matching branch names. Only these branches will be affected by the selected suppression strategy. Default
^$
.
- suppress-strategy (str):
Select what to suppress for branches matching the regex. Valid values:
suppress-nothing
(default),suppress-branch-indexing
, orsuppress-webhooks
.Note
Using
suppress-scm-triggering: true
is deprecated since Branch API 2.1045.v4ec3ed07b_e4f.
- 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