Git

13 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.
Table 1. Git parameters
Parameter Type Description

remote

String

Specify the URL of this remote repository. This uses the same syntax as your git clone command.

browser (optional)

Nested choice of GitRepositoryBrowser objects

credentialsId (optional)

String

Credentials used to scan branches and check out sources.

extensions (optional)

List of Nested Choice of GitSCMExtension objects

gitTool (optional)

String

id (optional)

String

traits (optional)

List of Nested Choice of SCMSourceTrait objects

GitRepositoryBrowser objects

  • $class: 'AssemblaWeb'

    AssemblaWeb

    Table 2. AssemblaWeb parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'BitbucketWeb'

    BitbucketWeb

    Table 3. BitbucketWeb parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'CGit'

    CGit

    Table 4. CGit parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'FisheyeGitRepositoryBrowser'

    FishEye

    Table 5. FisheyeGitRepositoryBrowser parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'GitBlitRepositoryBrowser'

    GitBlit

    Table 6. GitBlitRepositoryBrowser parameters
    Parameter Type Description

    repoUrl

    String

    projectName

    String

    Specify the name of the project in GitBlit.

  • $class: 'GitLab'

    GitLab

    Table 7. GitLab parameters
    Parameter 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 parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'GitWeb'

    GitWeb

    Table 9. GitWeb parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'GithubWeb'

    GithubWeb

    Table 10. GithubWeb parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'gitiles'

    Gitiles

    Table 11. gitiles parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'GitoriousWeb'

    GitoriousWeb

    Table 12. GitoriousWeb parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'GogsGit'

    Gogs

    Table 13. GogsGit parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'KilnGit'

    Kiln

    Table 14. KilnGit parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'Phabricator'

    Phabricator

    Table 15. Phabricator parameters
    Parameter 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 parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'RhodeCode'

    RhodeCode

    Table 17. RhodeCode parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'Stash'

    Stash

    Table 18. Stash parameters
    Parameter Type Description

    repoUrl

    String

  • $class: 'TFS2013GitRepositoryBrowser'

    Microsoft Team Foundation Server/Visual Studio Team Services

    Table 19. TFS2013GitRepositoryBrowser parameters
    Parameter 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 parameters
    Parameter 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 parameters
    Parameter Type Description

    buildChooser

    Nested Choice of BuildChooser objects

  • $class: 'ChangelogToBranch'

    This method calculates the changelog against the specified branch.

    Table 22. ChangelogToBranch parameters
    Parameter Type Description

    options

  • $class: 'CheckoutOption'

    Advanced checkout behaviors.

    Table 23. ChangelogToBranch parameters
    Parameter 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 parameters
    Parameter 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 named main, and a remote branch origin/develop/new-feature will be checked out to a local branch named develop/newfeature. This option has not been tested with submodules.

    Table 25. LocalBranch parameters
    Parameter Type Description

    localBranch

    String

  • $class: 'MessageExclusion'

    Polling ignores commits with certain messages.

    Table 26. MessageExclusion parameters
    Parameter 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.

    Exclusion uses Pattern matching.

    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 parameters
    Parameter 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.

    Example
    myapp/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 the main 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 parameters
    Parameter Type Description

    options

  • $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 parameters
    Parameter 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 parameters
    Parameter 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 parameters
    Parameter Type Description

    sparseCheckoutPaths

    List of Nested SparseCheckoutPath object

  • $class: 'SubmoduleOption'

    Advanced sub-modules behaviors.

    Table 32. SubmoduleOption parameters
    Parameter 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 parameters
    Parameter 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.

    Example
    auto_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 parameters
    Parameter 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 parameters
    Parameter 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 parameters
    Parameter Type Description

    extension

  • $class: 'CleanAfterCheckoutTrait'

    Clean after checkout.

  • $class: 'CleanBeforeCheckoutTrait'

    Clean before checkout.

  • $class: 'CloneOptionTrait'

    Advanced clone behaviors.

    Table 37. CloneOptionTrait parameters
    Parameter Type Description

    extension

  • $class: 'GitLFSPullTrait'

    Git LFS pull after checkout.

  • $class: 'GitToolSCMSourceTrait'

    Table 38. GitToolSCMSourceTrait parameters
    Parameter 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 parameters
    Parameter Type Description

    templates

    List of Nested RefSpecTemplate object

  • headRegexFilter

    Filter by name (with regular expression)

    Table 40. headRegexFilter parameters
    Parameter 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 parameters
    Parameter Type Description

    remoteName

    String

  • $class: 'SparseCheckoutPathsTrait'

    Sparse Checkout paths.

    Table 42. SparseCheckoutPathsTrait parameters
    Parameter Type Description

    extension

  • $class: 'SubmoduleOptionTrait'

    Advanced sub-modules behaviors

    Table 43. SubmoduleOptionTrait parameters
    Parameter Type Description

    extension

  • $class: 'UserIdentityTrait'

    Custom user/e-mail address.

    Table 44. UserIdentityTrait parameters
    Parameter Type Description

    extension

  • headWildcardFilter

    Filter by name (with wildcards)

    Table 45. headWildcardFilter parameters
    Parameter 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 parameters
    Parameter 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 be test-@{1}.

  • $class: 'GitBrowserSCMSourceTrait'

    Configure Repository Browser.

    Table 47. GitBrowserSCMSourceTrait parameters
    Parameter 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

Table 48. ChangelogToBranchOptions object parameters
Parameter Type Description

compareRemote

String

Name of the repository, such as origin, that contains the branch you specify below.

compareTarget

String

The name of the branch within the named repository to compare against.

UserMergeOptions object

Table 49. UserMergeOptions object parameters
Parameter Type Description

mergeTarget

String

The name of the branch within the named repository to merge to, such as main.

fastForwardMode (optional)

Values: FF, FF_ONLY, NO_FF

Merge fast-forward mode selection.

The default, --ff, gracefully falls back to a merge commit when required.

For more information, see the Git Merge Documentation.

mergeRemote (optional)

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.

mergeStrategy

Values: DEFAULT, RESOLVE, RECURSIVE, OCTOPUS,OURS, SUBTREE, RECURSIVE_THEIRS

Merge strategy selection. This feature is not fully implemented in JGIT.

CheckoutOption object

Advanced checkout behaviors.

Table 50. CheckoutOption object parameters
Parameter 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.

CloneOption object

Advanced clone behaviors.

Table 51. CloneOption object parameters
Parameter 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 (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.

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.

RefSpecTemplate object

Ref Spec

Table 52. RefSpecTemplate object parameters
Parameter Type Description

value

String

A ref spec to fetch. Any occurrences of @{remote} will be replaced by the remote name (which defaults to origin) before use.

SparseCheckoutPath object

Path

Table 53. SparseCheckoutPath parameters
Parameter Type Description

path

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.

Table 54. SparseCheckoutPaths object parameters
Parameter Type Description

sparseCheckoutPaths

List of Nested SparseCheckoutPath object

SubmoduleOption object

Advanced submodules behaviors.

Table 55. Submodule object parameters
Parameter Type Description

disableSubmodules

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.

recursiveSubmodules

boolean

Retrieve all submodules recursively (uses '--recursive' option which requires Git version 1.6.5 or higher).

trackingSubmodules

boolean

Retrieve the tip of the configured branch in .gitmodules (uses '--remote' option which requires Git version 1.8.2 or higher).

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

UserIdentity object

Custom user name/email address.

Table 56. UserIdentity object parameters
Parameter 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.