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. |
Parameter | Type | Description |
---|---|---|
|
String |
Specify the URL of this remote repository. This uses the same syntax as your git clone command. |
|
Nested choice of GitRepositoryBrowser objects |
|
|
String |
Credentials used to scan branches and check out sources. |
|
List of Nested Choice of GitSCMExtension objects |
|
|
String |
|
|
String |
|
|
List of Nested Choice of SCMSourceTrait objects |
GitRepositoryBrowser objects
-
$class: 'AssemblaWeb'
AssemblaWeb
Table 2. AssemblaWeb
parametersParameter Type Description repoUrl
String
-
$class: 'BitbucketWeb'
BitbucketWeb
Table 3. BitbucketWeb
parametersParameter Type Description repoUrl
String
-
$class: 'CGit'
CGit
Table 4. CGit
parametersParameter Type Description repoUrl
String
-
$class: 'FisheyeGitRepositoryBrowser'
FishEye
Table 5. FisheyeGitRepositoryBrowser
parametersParameter Type Description repoUrl
String
-
$class: 'GitBlitRepositoryBrowser'
GitBlit
Table 6. GitBlitRepositoryBrowser
parametersParameter Type Description repoUrl
String
projectName
String
Specify the name of the project in GitBlit.
-
$class: 'GitLab'
GitLab
Table 7. GitLab
parametersParameter Type Description repoUrl
String
Specify the root URL serving this repository (such as
http://gitlabserver:port/group/repo
).version
(optional)String
Specify the major and minor version of GitLab you use (such as 9.1). If you don’t specify a version, a modern version of GitLab (>= 8.0) is assumed.
-
$class: 'GitList'
GitList
Table 8. GitList
parametersParameter Type Description repoUrl
String
-
$class: 'GitWeb'
GitWeb
Table 9. GitWeb
parametersParameter Type Description repoUrl
String
-
$class: 'GithubWeb'
GithubWeb
Table 10. GithubWeb
parametersParameter Type Description repoUrl
String
-
$class: 'gitiles'
Gitiles
Table 11. gitiles
parametersParameter Type Description repoUrl
String
-
$class: 'GitoriousWeb'
GitoriousWeb
Table 12. GitoriousWeb
parametersParameter Type Description repoUrl
String
-
$class: 'GogsGit'
Gogs
Table 13. GogsGit
parametersParameter Type Description repoUrl
String
-
$class: 'KilnGit'
Kiln
Table 14. KilnGit
parametersParameter Type Description repoUrl
String
-
$class: 'Phabricator'
Phabricator
Table 15. Phabricator
parametersParameter Type Description repoUrl
String
repo
String
Specify the repository name in Phabricator (for example, the "foo" part of
phabricator.example.com/diffusion/foo/browse
). -
$class: 'RedmineWeb'
RedmineWeb
Table 16. RedmineWeb
parametersParameter Type Description repoUrl
String
-
$class: 'RhodeCode'
RhodeCode
Table 17. RhodeCode
parametersParameter Type Description repoUrl
String
-
$class: 'Stash'
Stash
Table 18. Stash
parametersParameter Type Description repoUrl
String
-
$class: 'TFS2013GitRepositoryBrowser'
Microsoft Team Foundation Server/Visual Studio Team Services
Table 19. TFS2013GitRepositoryBrowser
parametersParameter Type Description repoUrl
String
Either the name of the remote whose URL should be used, or the URL of this module in TFS. If empty (default), the URL of the "origin" repository is used. If TFS is also used as the repository server, this can usually be left blank.
-
$class: 'ViewGitWeb'
ViewGit
Table 20. Stash
parametersParameter Type Description repoUrl
String
projectName
String
Specify the name of the project in ViewGit.
GitSCMExtension objects
-
$class: 'AuthorInChangeLog'
The default behavior is to use the Git commit’s "Committer" value in Jenkins' build changesets. If this option is selected, the Git commit’s "Author" value would be used instead.
-
$class: 'BuildChooserSetting'
When you are interested in using a job to build multiple heads (most typically multiple branches), you can choose how Jenkins selects what branches to build in what order. This extension point in Jenkins is used by many other plugins to control the job to build specific commits. When you activate those plugins, you may see them installing a custom strategy here.
Table 21. BuildChooserSetting
parametersParameter Type Description buildChooser
Nested Choice of BuildChooser objects
-
$class: 'ChangelogToBranch'
This method calculates the changelog against the specified branch.
Table 22. ChangelogToBranch
parametersParameter Type Description options
-
$class: 'CheckoutOption'
Advanced checkout behaviors.
Table 23. ChangelogToBranch
parametersParameter Type Description timeout
int
Specify a timeout (in minutes) for checkout. This option overrides the default timeout of 10 minutes. You can change the global git timeout via the property
org.jenkinsci.plugins.gitclient.Git.timeOut
. Property should be set on both controller and agent to have effect. -
$class: 'CleanBeforeCheckout'
Clean up the workspace before every checkout by deleting all untracked files and directories, including those which are specified in
.gitignore
. It also resets all tracked files to their versioned state. This ensures that the workspace is in the same state as if you cloned and checked out in a brand-new empty directory, and ensures that your build is not affected by the files generated by the previous build. -
$class: 'CleanCheckout'
Clean up the workspace after every checkout by deleting all untracked files and directories, including those which are specified in
.gitignore
. It also resets all tracked files to their versioned state. This ensures that the workspace is in the same state as if you cloned and checked out in a brand-new empty directory, and ensures that your build is not affected by the files generated by the previous build. -
$class: 'CloneOption'
Advanced clone behaviors.
Table 24. CloneOption
parametersParameter Type Description shallow
boolean
Perform shallow clone, so that Git will not download the history of the project, saving time and disk space when you just want to access the latest version of a repository.
noTags
boolean
Deselect this to perform a clone without tags, saving time and disk space when you just want to access what is specified by the refspec.
reference
String
Specify a folder containing a repository that will be used by Git as a reference during clone operations. This option will be ignored if the folder is not available on the controller or agent where the clone is being executed.
timeout
int
Specify a timeout (in minutes) for clone and fetch operations. This option overrides the default timeout of 10 minutes. You can change the global git timeout via the property
org.jenkinsci.plugins.gitclient.Git.timeOut
. Property should be set on both controller and agent to have effect.depth
int
Set shallow clone depth, so that Git will only download recent history of the project, saving time and disk space when you just want to access the latest commits of a repository.
honorRefspec
(optional)boolean
Perform initial clone using the refspec defined for the repository. This can save time, data transfer and disk space when you only need to access the references specified by the refspec.
-
$class: 'DisableRemotePoll'
Git plugin uses
git ls-remote
polling mechanism by default when configured with a single branch (no wildcards). This compares the latest built commit SHA with the remote branch without cloning a local copy of the repo. You can use this option to disable the default behavior. If this option is selected, polling will require a workspace and might trigger unwanted builds. -
$class: 'EnforceGitClient'
Enforce JGit Client.
-
$class: 'GitLFSPull'
Git LFS pull after checkout.
-
$class: 'IgnoreNotifyCommit'
If checked, this repository will be ignored when the
notifyCommit-URL
is accessed regardless of if the repository matches or not. -
$class: 'LocalBranch'
If given, checkout the revision to build as HEAD on this branch. If selected, and its value is an empty string or "**", then the branch name is computed from the remote branch without the origin. In that case, a remote branch
origin/main
will be checked out to a local branch namedmain
, and a remote branchorigin/develop/new-feature
will be checked out to a local branch nameddevelop/newfeature
. This option has not been tested with submodules.Table 25. LocalBranch
parametersParameter Type Description localBranch
String
-
$class: 'MessageExclusion'
Polling ignores commits with certain messages.
Table 26. MessageExclusion
parametersParameter Type Description excludeMessage
String
If set, and Jenkins is set to poll for changes, Jenkins will ignore any revisions committed with message matched to Pattern when determining if a build needs to be triggered.
This can be used to exclude commits done by the build itself from triggering another build, assuming the build server commits the change with a distinct message.
Example 1.*\[maven-release-plugin\].*
The example above illustrates that if only revisions with "[maven-release-plugin]" message in first comment line have been committed to the SCM a build will not occur.
You can create more complex patterns using embedded flag expressions.
Example 2(?s).*FOO.*
This example will search for a "FOO" message in all comment lines.
-
$class: 'PathRestriction'
If set, and Jenkins is set to poll for changes, Jenkins will pay attention to included and/or excluded files and/or folders when determining if a build needs to be triggered. Using this behavior will preclude the faster
git ls-remote
polling mechanism, forcing polling to require a workspace thus sometimes triggering unwanted builds, as if you had selected the Force polling using workspace extension as well.Table 27. PathRestriction
parametersParameter Type Description includedRegions
String
Each inclusion uses Java regular expression pattern matching, and must be separated by a new line. An empty list implies that everything is included. .Example
myapp/src/main/web/.*\.html myapp/src/main/web/.*\.jpeg myapp/src/main/web/.*\.gif
The example above illustrates that a build will only occur, if
html/jpeg/gif
files have been committed to the SCM.Exclusions take precedence over inclusions, if there is an overlap between included and excluded regions.
excludedRegions
String
Each exclusion uses Java regular expression pattern matching, and must be separated by a new line.
Examplemyapp/src/main/web/.*\.html myapp/src/main/web/.*\.jpeg myapp/src/main/web/.*\.gif
The example above illustrates that if only
html/jpeg/gif
files have been committed to the SCM a build will not occur. -
$class: 'PerBuildTag'
Create a tag in the workspace for every build to unambiguously mark the commit that was built. You can combine this with Git publisher to push the tags to the remote repository.
-
$class: 'PreBuildMerge'
These options allow you to perform a merge to a particular branch before building. For example, you could specify an integration branch to be built, and to merge to
main
. In this scenario, on every change of integration, Jenkins will perform a merge with themain
branch, and try to perform a build if the merge is successful. It then may push the merge back to the remote repository if the Git Push post-build action is selected.Table 28. PreBuildMerge
parametersParameter Type Description options
Nested UserMergeOptions object
-
$class: 'PruneStaleBranch'
Run
git remote prune
for each remote, to prune obsolete local branches. -
$class: 'RelativeTargetDirectory'
Check out to a sub-directory.
Table 29. RelativeTargetDirectory
parametersParameter Type Description relativeTargetDir
String
Specify a local directory (relative to the workspace root) where the Git repository will be checked out. If left empty, the workspace root itself will be used.
-
$class: 'ScmName'
Unique name for this SCM. Needed when using Git within the Multi SCM plugin.
Table 30. ScmName
parametersParameter Type Description name
String
-
$class: 'SparseCheckoutPaths'
Specify the paths that you’d like to sparse checkout. This may be used for saving space (consider a reference repository). Be sure to use a recent version of Git, at least above 1.7.10.
Table 31. SparseCheckoutPaths
parametersParameter Type Description sparseCheckoutPaths
List of Nested SparseCheckoutPath object
-
$class: 'SubmoduleOption'
Advanced sub-modules behaviors.
Table 32. SubmoduleOption
parametersParameter Type Description disableSubmodules
boolean
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.
recursiveSubmodules
boolean
Retrieve all submodules recursively (uses '--recursive' option which requires git>=1.6.5).
trackingSubmodules
boolean
Retrieve the tip of the configured branch in
`.gitmodules
(Uses '--remote' option which requires git>=1.8.2).reference
String
Specify a folder containing a repository that will be used by Git as a reference during clone operations.
This option will be ignored if the folder is not available on the controller or agent where the clone is being executed.
To prepare a reference folder with multiple subprojects, create a bare Git repository and add all the remote urls then perform a fetch using the following commands:
git init --bare git remote add SubProject1 https://gitrepo.com/subproject1 git remote add SubProject2 https://gitrepo.com/subproject2 git fetch --all
timeout
int
Specify a timeout (in minutes) for submodules operations.
This option overrides the default timeout of 10 minutes.
You can change the global Git timeout via the property
org.jenkinsci.plugins.gitclient.Git.timeOut
. Property should be set on both controller and agent to have effect.parentCredentials
boolean
Use credentials from the default remote of the parent project.
depth
(optional)int
Set shallow clone depth, so that Git will only download recent history of the project, saving time and disk space when you just want to access the latest commits of a repository.
shallow
(optional)boolean
Perform shallow clone, so that Git will not download the history of the project, saving time and disk space when you just want to access the latest version of a repository.
threads
(optional)int
-
$class: 'UserExclusion'
Polling ignores commits from certain users.
Table 33. UserExclusion
parametersParameter Type Description excludedUsers
String
If set, and Jenkins is set to poll for changes, Jenkins will ignore any revisions committed by users in this list when determining if a build needs to be triggered.
This can be used to exclude commits done by the build itself from triggering another build, assuming the build server commits the change with a distinct SCM user.
Using this behavior will preclude the faster
git ls-remote
polling mechanism, forcing polling to require a workspace thus sometimes triggering unwanted builds, as if you had selected the Force polling using workspace extension as well.Each exclusion uses literal pattern matching, and must be separated by a new line.
Exampleauto_build_user
The example above illustrates that if only revisions by "auto_build_user" have been committed to the SCM a build will not occur.
-
$class: 'UserIdentity'
Custom user name/e-mail address.
Table 34. UserIdentity
parametersParameter Type Description name
String
If given,
git config user.name [this]
is called before builds. This overrides whatever is in the global settings.email
String
If given,
git config user.email [this]
is called before builds. This overrides whatever is in the global settings. -
$class: 'WipeWorkspace'
Delete the contents of the workspace before building, ensuring a fully fresh workspace.
BuildChooser objects
-
$class: 'AncestryBuildChooser'
Ancestry
Table 35. AncestryBuildChooser
parametersParameter Type Description maximumAgeInDays
int
ancestorCommitSha1
String
-
$class: 'DefaultBuildChooser'
Default
-
$class: 'InverseBuildChooser'
Inverse
SCMSourceTrait objects
-
$class: 'AuthorInChangelogTrait'
Use Commit author in changelog.
-
$class: 'CheckoutOptionTrait'
Advanced checkout behaviors.
Table 36. CheckoutOptionTrait
parametersParameter Type Description extension
Nested CheckoutOption object
-
$class: 'CleanAfterCheckoutTrait'
Clean after checkout.
-
$class: 'CleanBeforeCheckoutTrait'
Clean before checkout.
-
$class: 'CloneOptionTrait'
Advanced clone behaviors.
Table 37. CloneOptionTrait
parametersParameter Type Description extension
Nested CloneOption object
-
$class: 'GitLFSPullTrait'
Git LFS pull after checkout.
-
$class: 'GitToolSCMSourceTrait'
Table 38. GitToolSCMSourceTrait
parametersParameter Type Description gitTool
String
-
$class: 'LocalBranchTrait'
Checkout to matching local branches.
-
$class: 'PruneStaleBranchTrait'
Prune stale remote-tracking branches.
-
$class: 'RefSpecsSCMSourceTrait'
Specify ref specs.
Table 39. RefSpecsSCMSourceTrait
parametersParameter Type Description templates
List of Nested RefSpecTemplate object
-
headRegexFilter
Filter by name (with regular expression)
Table 40. headRegexFilter
parametersParameter Type Description regex
String
A Java regular expression to restrict the names. Names that do not match the supplied regular expression will be ignored.
This filter will be applied to all branch like things, including change requests. -
$class: 'RemoteNameSCMSourceTrait'
Configure remote name.
Table 41. RemoteNameSCMSourceTrait
parametersParameter Type Description remoteName
String
-
$class: 'SparseCheckoutPathsTrait'
Sparse Checkout paths.
Table 42. SparseCheckoutPathsTrait
parametersParameter Type Description extension
Nested SparseCheckoutPaths object
-
$class: 'SubmoduleOptionTrait'
Advanced sub-modules behaviors
Table 43. SubmoduleOptionTrait
parametersParameter Type Description extension
Nested SubmoduleOption object
-
$class: 'UserIdentityTrait'
Custom user/e-mail address.
Table 44. UserIdentityTrait
parametersParameter Type Description extension
Nested UserIdentity object
-
headWildcardFilter
Filter by name (with wildcards)
Table 45. headWildcardFilter
parametersParameter Type Description includes
String
Space-separated list of name patterns to consider. You may use
*
as a wildcard; for example:main release*
.This filter will be applied to all branch like things, including change requests. excludes
String
Space-separated list of name patterns to ignore even if matched by the includes list. For example: release
alpha-* beta-*
.This filter will be applied to all branch like things, including change requests. -
$class: 'WipeWorkspaceTrait'
Wipe out repository data and force clone.
-
$class: 'DiscoverOtherRefsTrait'
Discovers other specified refs on the repository.
Table 46. DiscoverOtherRefsTrait
parametersParameter Type Description ref
String
The pattern under
/refs
on the remote repository to discover, can contain a wildcard. Example:test/*/merged
nameMapping
(optional)String
Mapping for how the ref can be named in, for example, the
@Library
.Example:
test-@{1}
Where
@{1}
replaces the first wildcard in the ref when discovered.By default it will be
namespace_before_wildcard-@{1}
.For example, if ref is
test/*/merged
the default mapping would betest-@{1}
. -
$class: 'GitBrowserSCMSourceTrait'
Configure Repository Browser.
Table 47. GitBrowserSCMSourceTrait
parametersParameter Type Description browser
Nested Choice of GitRepositoryBrowser objects
-
$class: 'IgnoreOnPushNotificationTrait'
Ignore on push notifications.
-
gitBranchDiscovery
Discovers branches on the repository.
-
gitTagDiscovery
Discovers tags on the repository.
Nested objects
ChangelogToBranchOptions object
Parameter | Type | Description |
---|---|---|
|
String |
Name of the repository, such as origin, that contains the branch you specify below. |
|
String |
The name of the branch within the named repository to compare against. |
UserMergeOptions object
Parameter | Type | Description |
---|---|---|
|
String |
The name of the branch within the named repository to merge to, such as |
|
Values: |
Merge fast-forward mode selection. The default, For more information, see the Git Merge Documentation. |
|
String |
Name of the repository, such as origin, that contains the branch you specify below. If left blank, it’ll default to the name of the first repository configured above. |
|
Values: |
Merge strategy selection. This feature is not fully implemented in JGIT. |
CheckoutOption object
Advanced checkout behaviors.
Parameter | Type | Description |
---|---|---|
|
int |
Specify a timeout (in minutes) for checkout. This option overrides the default timeout of 10 minutes. You can change the global git timeout via the property Property should be set on both controller and agent to have effect. |
CloneOption object
Advanced clone behaviors.
Parameter | Type | Description |
---|---|---|
|
boolean |
Perform shallow clone, so that Git will not download the history of the project, saving time and disk space when you just want to access the latest version of a repository. |
|
boolean |
Deselect this to perform a clone without tags, saving time and disk space when you just want to access what is specified by the refspec. |
|
String |
Specify a folder containing a repository that will be used by Git as a reference during clone operations. This option will be ignored if the folder is not available on the controller or agent where the clone is being executed. |
|
int |
Specify a timeout (in minutes) for clone and fetch operations. This option overrides the default timeout of 10 minutes. You can change the global git timeout via the property |
|
int |
Set shallow clone depth, so that Git will only download recent history of the project, saving time and disk space when you just want to access the latest commits of a repository. |
|
boolean |
Perform initial clone using the refspec defined for the repository. This can save time, data transfer and disk space when you only need to access the references specified by the refspec. |
RefSpecTemplate object
Ref Spec
Parameter | Type | Description |
---|---|---|
|
String |
A ref spec to fetch. Any occurrences of |
SparseCheckoutPath object
Path
Parameter | Type | Description |
---|---|---|
|
String |
SparseCheckoutPaths object
Specify the paths that you’d like to sparse checkout. This may be used for saving space (for example, a reference repository). Be sure to use a recent version of Git, at least above 1.7.10.
Parameter | Type | Description |
---|---|---|
|
List of Nested SparseCheckoutPath object |
SubmoduleOption object
Advanced submodules behaviors.
Parameter | Type | Description |
---|---|---|
|
boolean |
By disabling support for submodules you can still keep using basic Git plugin functionality and just have Jenkins ignore submodules completely as if they didn’t exist. |
|
boolean |
Retrieve all submodules recursively (uses '--recursive' option which requires Git version 1.6.5 or higher). |
|
boolean |
Retrieve the tip of the configured branch in |
|
String |
Specify a folder containing a repository that will be used by Git as a reference during clone operations. This option will be ignored if the folder is not available on the controller or agent where the clone is being executed. To prepare a reference folder with multiple subprojects, create a bare Git repository and add all the remote urls then perform a fetch using the following commands:
|
|
int |
Specify a timeout (in minutes) for submodules operations. This option overrides the default timeout of 10 minutes. You can change the global git timeout via the property |
|
boolean |
Use credentials from the default remote of the parent project. |
|
int |
Set shallow clone depth, so that Git will only download recent history of the project, saving time and disk space when you just want to access the latest commits of a repository. |
|
boolean |
Perform shallow clone, so that Git will not download the history of the project, saving time and disk space when you just want to access the latest version of a repository. |
|
int |
UserIdentity object
Custom user name/email address.
Parameter | Type | Description |
---|---|---|
|
String |
If given, |
|
String |
If given, |