scmGit

The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

scmGit

scmGit

The git plugin provides fundamental git operations for Jenkins projects. It can poll, fetch, checkout, and merge contents of git repositories.

The git plugin provides an SCM implementation to be used with the Pipeline SCM checkout step. The Pipeline Syntax Snippet Generator guides the user to select git plugin checkout options and provides online help for each of the options.

Use the Pipeline Snippet Generator to generate a sample pipeline script for the checkout step. Examples of the checkout step include:

Checkout step with defaults
Checkout step with https and a specific branch
Checkout step with ssh and a private key credential
Checkout step with https and changelog disabled
Checkout step with git protocol and polling disabled

See the argument descriptions for more details.

The checkout step provides access to all the Pipeline capabilities provided by the git plugin:

checkout scmGit(userRemoteConfigs: [
                    [ url: 'https://github.com/jenkinsci/git-plugin' ]
                ])

NOTE: The checkout step is the preferred SCM checkout method. For simpler cases that do not require all the capabilities of the git plugin, the git step can also be used.

Use the Pipeline Snippet Generator to generate a sample pipeline script for the checkout step.

The checkout step can be used in many cases where the git step cannot be used. Refer to the git plugin documentation for detailed descriptions of options available to the checkout step. For example, the checkout step supports:

SHA-1 checkout
Tag checkout
Submodule checkout
Sparse checkout
Large file checkout (LFS)
Reference repositories
Branch merges
Repository tagging
Custom refspecs
Timeout configuration
Changelog calculation against a non-default reference
Stale branch pruning

Example: Checkout step with defaults

Checkout from the git plugin source repository using https protocol, no credentials, and the master branch.

The Pipeline Snippet Generator generates this example:

checkout scmGit(userRemoteConfigs: [
                    [ url: 'https://github.com/jenkinsci/git-plugin' ]
                ])

Example: Checkout step with https and a specific branch

Checkout from the Jenkins source repository using https protocol, no credentials, and a specific branch (stable-2.289).

The Pipeline Snippet Generator generates this example:

checkout scmGit(branches: [[name: 'stable-2.289']],
                userRemoteConfigs: [
                    [ url: 'https://github.com/jenkinsci/jenkins.git' ]
                ])

Example: Checkout step with ssh and a private key credential

Checkout from the git client plugin source repository using ssh protocol, private key credentials, and the master branch. The credential must be a private key credential if the remote git repository is accessed with the ssh protocol. The credential must be a username / password credential if the remote git repository is accessed with http or https protocol.

The Pipeline Snippet Generator generates this example:

checkout changelog: false,
         scm: scmGit(userRemoteConfigs: [
                         [ credentialsId: 'my-private-key-credential-id',
                           url: 'git@github.com:jenkinsci/git-client-plugin.git' ]
                         ])

Example: Checkout step with https and changelog disabled

Checkout from the Jenkins source repository using https protocol, no credentials, the master branch, and changelog calculation disabled. If changelog is false, then the changelog will not be computed for this job. If changelog is true or is not set, then the changelog will be computed. See the workflow scm step documentation for more changelog details.

The Pipeline Snippet Generator generates this example:

checkout changelog: false,
         scmGit(userRemoteConfigs: [
                    [ url: 'https://github.com/jenkinsci/credentials-plugin' ]
                ])

Example: Checkout step with git protocol and polling disabled

Checkout from the command line git repository using git protocol, no credentials, the master branch, and no polling for changes. If poll is false, then the remote repository will not be polled for changes. If poll is true or is not set, then the remote repository will be polled for changes. See the workflow scm step documentation for more polling details.

The Pipeline Snippet Generator generates this example:

checkout poll: false,
         scmGit(userRemoteConfigs: [
                    [ url: 'git://git.kernel.org/pub/scm/git/git.git ]
                ])

Argument Descriptions

userRemoteConfigs
Specify the repository to track. This can be a URL or a local file path. Note that for super-projects (repositories with submodules), only a local file path or a complete URL is valid. The following are examples of valid git URLs.
- ssh://git@github.com/github/git.git
- git@github.com:github/git.git (short notation for ssh protocol)
- ssh://user@other.host.com/~/repos/R.git (to access the repos/R.git repository in the user's home directory)
- https://github.com/github/git.git
If the repository is a super-project, the location from which to clone submodules is dependent on whether the repository is bare or non-bare (i.e. has a working directory).
- If the super-project is bare, the location of the submodules will be taken from .gitmodules.
- If the super-project is not bare, it is assumed that the repository has each of its submodules cloned and checked out appropriately. Thus, the submodules will be taken directly from a path like ${SUPER_PROJECT_URL}/${SUBMODULE}, rather than relying on information from .gitmodules.
For a local URL/path to a super-project, git rev-parse --is-bare-repository is used to detect whether the super-project is bare or not.
For a remote URL to a super-project, the ending of the URL determines whether a bare or non-bare repository is assumed:
- If the remote URL ends with .git, a non-bare repository is assumed.
- If the remote URL does NOT end with .git, a bare repository is assumed.
- url : String
  Specify the URL or path of the git repository. This uses the same syntax as your git clone command.
- name : String
  ID of the repository, such as origin, to uniquely identify this repository among other remote repositories. This is the same "name" that you use in your git remote command. If left empty, Jenkins will generate unique names for you.
  You normally want to specify this when you have multiple remote repositories.
- refspec : String
  A refspec controls the remote refs to be retrieved and how they map to local refs. If left blank, it will default to the normal behaviour of git fetch, which retrieves all the branch heads as remotes/REPOSITORYNAME/BRANCHNAME. This default behaviour is OK for most cases.
  In other words, the default refspec is "+refs/heads/*:refs/remotes/REPOSITORYNAME/*" where REPOSITORYNAME is the value you specify in the above "name of repository" textbox.
  
  When do you want to modify this value? A good example is when you want to just retrieve one branch. For example, +refs/heads/master:refs/remotes/origin/master would only retrieve the master branch and nothing else.
  
  The plugin uses a default refspec for its initial fetch, unless the "Advanced Clone Option" is set to honor refspec. This keeps compatibility with previous behavior, and allows the job definition to decide if the refspec should be honored on initial clone.
  
  Multiple refspecs can be entered by separating them with a space character. +refs/heads/master:refs/remotes/origin/master +refs/heads/develop:refs/remotes/origin/develop retrieves the master branch and the develop branch and nothing else.
  
  See the refspec definition in Git user manual for more details.
- credentialsId : String
  Credential used to check out sources.
branches
List of branches to build. Jenkins jobs are most effective when each job builds only a single branch. When a single job builds multiple branches, the changelog comparisons between branches often show no changes or incorrect changes.
- name : String
  Specify the branches if you'd like to track a specific branch in a repository. If left blank, all branches will be examined for changes and built.
  
  The safest way is to use the refs/heads/<branchName> syntax. This way the expected branch is unambiguous.
  
  If your branch name has a / in it make sure to use the full reference above. When not presented with a full path the plugin will only use the part of the string right of the last slash. Meaning foo/bar will actually match bar.
  
  If you use a wildcard branch specifier, with a slash (e.g. release/), you'll need to specify the origin repository in the branch names to make sure changes are picked up. So e.g. origin/release/
  
  Possible options:
  - <branchName>
    Tracks/checks out the specified branch. If ambiguous the first result is taken, which is not necessarily the expected one. Better use refs/heads/<branchName>.
    E.g. master, feature1, ...
  - refs/heads/<branchName>
    Tracks/checks out the specified branch.
    E.g. refs/heads/master, refs/heads/feature1/master, ...
  - <remoteRepoName>/<branchName>
    Tracks/checks out the specified branch. If ambiguous the first result is taken, which is not necessarily the expected one.
    Better use refs/heads/<branchName>.
    E.g. origin/master
  - remotes/<remoteRepoName>/<branchName>
    Tracks/checks out the specified branch.
    E.g. remotes/origin/master
  - refs/remotes/<remoteRepoName>/<branchName>
    Tracks/checks out the specified branch.
    E.g. refs/remotes/origin/master
  - <tagName>
    This does not work since the tag will not be recognized as tag.
    Use refs/tags/<tagName> instead.
    E.g. git-2.3.0
  - refs/tags/<tagName>
    Tracks/checks out the specified tag.
    E.g. refs/tags/git-2.3.0
  - <commitId>
    Checks out the specified commit.
    E.g. 5062ac843f2b947733e6a3b105977056821bd352, 5062ac84, ...
  - ${ENV_VARIABLE}
    It is also possible to use environment variables. In this case the variables are evaluated and the result is used as described above.
    E.g. ${TREEISH}, refs/tags/${TAGNAME}, ...
  - <Wildcards>
    The syntax is of the form: REPOSITORYNAME/BRANCH. In addition, BRANCH is recognized as a shorthand of */BRANCH, '*' is recognized as a wildcard, and '**' is recognized as wildcard that includes the separator '/'. Therefore, origin/branches* would match origin/branches-foo but not origin/branches/foo, while origin/branches** would match both origin/branches-foo and origin/branches/foo.
  - :<regular expression>
    The syntax is of the form: :regexp. Regular expression syntax in branches to build will only build those branches whose names match the regular expression.
    Examples:
    
    :^(?!(origin/prefix)).*
    
    matches: origin or origin/master or origin/feature
    
    does not match: origin/prefix or origin/prefix_123 or origin/prefix-abc
    
    :origin/release-\d{8}
    
    matches: origin/release-20150101
    
    does not match: origin/release-2015010 or origin/release-201501011 or origin/release-20150101-something
    
    :^(?!origin/master$|origin/develop$).*
    
    matches: origin/branch1 or origin/branch-2 or origin/master123 or origin/develop-123
    
    does not match: origin/master or origin/develop
browser
Defines the repository browser that displays changes detected by the git plugin.
- assembla
  - repoUrl : String
    Specify the root URL serving this repository (such as https://www.assembla.com/code/PROJECT/git/).
- $class: 'BacklogGitRepositoryBrowser'
  - repoName : String
  - repoUrl : String
- bitbucketServer
  - repoUrl : String
    Specify the Bitbucket Server root URL for this repository (such as https://bitbucket:7990/OWNER/REPO/).
- bitbucket
  - repoUrl : String
    Specify the root URL serving this repository (such as https://bitbucket.org/OWNER/REPO/).
- cgit
  - repoUrl : String
    Specify the root URL serving this repository (such as https://cgit.example.com:port/group/REPO/).
- fisheye
  - repoUrl : String
    Specify the URL of this repository in FishEye (such as https://fisheye.example.com/browse/project/).
- gitblit
  - repoUrl : String
    Specify the root URL serving this repository.
  - projectName : String
    Specify the name of the project in GitBlit.
- $class: 'GitBucketBrowser'
  - url : String
- gitLab
  - repoUrl : String
    Specify the root URL serving this repository (such as https://gitlab.com/username/repository/).
  - version : String (optional)
    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.
- gitLabBrowser
  Specify the HTTP URL for this project's GitLab page so that links to changes can be automatically generated by Jenkins. The URL needs to include the owner and project. If the GitLab server is https://gitLab.example.com then the URL for bob's skunkworks project might be https://gitLab.example.com/bob/skunkworks.
  - projectUrl : String
    Specify the HTTP URL for this project's GitLab page. The URL needs to include the owner and project so, for example, if the GitLab server is https://gitLab.example.com then the URL for bob's skunkworks project might be https://gitLab.example.com/bob/skunkworks
- gitList
  - repoUrl : String
    Specify the root URL serving this repository (such as https://gitlist.example.com/repo/).
- gitWeb
  - repoUrl : String
    Specify the root URL serving this repository (such as https://github.com/jenkinsci/jenkins.git).
- $class: 'GiteaBrowser'
  - repoUrl : String
    Specify the HTTP URL for this repository's Gitea page. The URL needs to include the owner and repository so, for example, if the Gitea server is https://gitea.example.com then the URL for bob's skunkworks project repository might be https://gitea.example.com/bob/skunkworks
- github
  - repoUrl : String
    Specify the HTTP URL for this repository's GitHub page (such as https://github.com/jquery/jquery).
- gitiles
  - repoUrl : String
    Specify the root URL serving this repository (such as https://gwt.googlesource.com/gwt/).
- $class: 'GitoriousWeb'
  - repoUrl : String
    Specify the root URL serving this repository (such as https://gitorious.org/gitorious/mainline).
- gogs
  - repoUrl : String
    Specify the root URL serving this repository (such as https://gogs.example.com/username/some-repo-url.git).
- kiln
  - repoUrl : String
    Specify the root URL serving this repository (such as https://khanacademy.kilnhg.com/Code/Website/Group/webapp).
- phabricator
  - repoUrl : String
    Specify the phabricator instance root URL (such as https://phabricator.example.com).
  - repo : String
    Specify the repository name in phabricator (such as the foo part of phabricator.example.com/diffusion/foo/browse).
- redmine
  - repoUrl : String
    Specify the root URL serving this repository (such as https://redmine.example.com/PATH/projects/PROJECT/repository).
- rhodeCode
  - repoUrl : String
    Specify the HTTP URL for this repository's RhodeCode page (such as https://rhodecode.example.com/projects/PROJECT/repos/REPO/).
- $class: 'ScmManagerGitRepositoryBrowser'
  - repoUrl : String
    Specify the root URL serving this repository (such as https://scm-manager.org/scm/repo/namespace/name).
- jbSpace
  - repoUrl : String
    Provide the absolute URL to your repository in JetBrains SpaceCode in the following format: https://<your SpaceCode instance>/p/<project key>/repositories/<repository name>
- $class: 'Stash'
  - repoUrl : String
    Specify the HTTP URL for this repository's Stash page (such as https://stash.example.com/projects/PROJECT/repos/REPO/).
- $class: 'TracGitRepositoryBrowser'
- $class: 'TuleapBrowser'
  Specify the HTTPS URL for the Tuleap Git repository so that links to changes can be automatically generated by Jenkins.
  - repositoryUrl : String
    The URL is the web URL of the Tuleap Git repository.
- viewgit
  - repoUrl : String
    Specify the root URL serving this repository (such as https://git.example.com/viewgit/).
  - projectName : String
    Specify the name of the project in ViewGit (e.g. scripts, scuttle etc. from https://code.fealdia.org/viewgit/).
gitTool : String
Name of the git tool to be used for this job. Git tool names are defined in "Global Tool Configuration".
extensions
Extensions add new behavior or modify existing plugin behavior for different uses. Extensions help users more precisely tune plugin behavior to meet their needs.

Extensions include:
- Clone extensions modify the git operations that retrieve remote changes into the agent workspace. The extensions can adjust the amount of history retrieved, how long the retrieval is allowed to run, and other retrieval details.
- Checkout extensions modify the git operations that place files in the workspace from the git repository on the agent. The extensions can adjust the maximum duration of the checkout operation, the use and behavior of git submodules, the location of the workspace on the disc, and more.
- Changelog extensions adapt the source code difference calculations for different cases.
- Tagging extensions allow the plugin to apply tags in the current workspace.
- Build initiation extensions control the conditions that start a build. They can ignore notifications of a change or force a deeper evaluation of the commits when polling.
- Merge extensions can optionally merge changes from other branches into the current branch of the agent workspace. They control the source branch for the merge and the options applied to the merge.
- 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 choose 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.
  - buildChooser
    - $class: 'AlternativeBuildChooser'
    - $class: 'AncestryBuildChooser'
      
      maximumAgeInDays : int
      
      ancestorCommitSha1 : String
    - $class: 'DefaultBuildChooser'
    - $class: 'DeflakeGitBuildChooser'
    - $class: 'GerritTriggerBuildChooser'
    - $class: 'InverseBuildChooser'
- buildSingleRevisionOnly
  Disable scheduling for multiple candidate revisions.
  If we have 3 branches:
  ----A--.---.--- B
  \-----C
  jenkins would try to build (B) and (C).
  This behaviour disables this and only builds one of them.
  It is helpful to reduce the load of the Jenkins infrastructure when the SCM system like Bitbucket or GitHub should decide what commits to build.
- changelogToBranch
  This method calculates the changelog against the specified branch.
  - options
    - 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.
- checkoutOption
  - 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 (see JENKINS-11286). Note that property should be set on both controller and agent to have effect (see JENKINS-22547).
- 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.
  - deleteUntrackedNestedRepositories : boolean (optional)
    Deletes untracked submodules and any other subdirectories which contain .git directories.
- cleanAfterCheckout
  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.
  - deleteUntrackedNestedRepositories : boolean (optional)
    Deletes untracked submodules and any other subdirectories which contain .git directories.
- cloneOption
  - 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 (see JENKINS-11286). Note that property should be set on both controller and agent to have effect (see JENKINS-22547).
  - depth : int (optional)
    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 : boolean (optional)
    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: 'CodeCommitURLHelper'
  - credentialId : String
    
    OPTIONAL: Select the credentials to use.
    If not specified, defaults to the DefaultAWSCredentialsProviderChain behaviour - *FROM THE JENKINS INSTANCE*
    
    In the latter case, usage of IAM Role Profiles seems not to work, thus relying on environment variables / system properties or the ~/.aws/credentials file, thus not recommended.
  - repositoryName : String
- $class: 'DisableRemotePoll'
  Git plugin uses git ls-remote polling mechanism by default when configured with a single branch (no wildcards!). This compare the latest built commit SHA with the remote branch without cloning a local copy of the repo.
  
  If you don't want to / can't use this.
  
  If this option is selected, polling will require a workspace and might trigger unwanted builds (see JENKINS-10131).
- $class: 'ExcludeFromChangeSet'
- $class: 'ExcludeFromPoll'
- firstBuildChangelog
  First builds will populate the changelog with the latest commit, if any, to allow Pipelines to check and test for file changes. By default, no changelog is generated for the first build because the first build has no predecessor build for comparison. When the first build changelog option is enabled, the most recent commit on the branch will be used as the changelog of the first build.
  - makeChangelog : boolean (optional)
- lfs
  Enable git large file support for the workspace by pulling large files after the checkout completes. Requires that the controller and each agent performing an LFS checkout have installed `git lfs`.
- $class: 'GitSCMChecksExtension'
  - verboseConsoleLog : boolean (optional)
    If this option is checked, verbose log will be output to build console; the verbose log is useful for debugging the publisher creation.
- $class: 'GitSCMStatusChecksExtension'
  - name : String (optional)
  - skip : boolean (optional)
  - skipProgressUpdates : boolean (optional)
  - suppressLogs : boolean (optional)
  - unstableBuildNeutral : boolean (optional)
- $class: 'GitTagMessageExtension'
  If the revision checked out has a git tag associated with it, the tag name will be exported during the build as GIT_TAG_NAME.
  If a message was specified when creating the tag, then that message will be exported during the build as the GIT_TAG_MESSAGE environment variable.
  If no tag message was specified, the commit message will be used.
  If you ticked the Use most recent tag option, and the revision checked out has no git tag associated with it, the parent commits will be searched for a git tag, and the rules stated above will apply to the first parent commit with a git tag.
  If the revision has more than one tag associated with it, only the most recent tag will be taken into account, unless the refspec contains "refs/tags/" — i.e. builds are only triggered when certain tag names or patterns are matched — in which case the exact tag name that triggered the build will be used, even if it's not the most recent tag for this commit.
  For this reason, if you're not using a tag-specific refspec but you are using the "Create a tag for every build" behaviour, you should make sure that the build-tagging behaviour is configured to run after this "export git tag message" behaviour.
  Tag and commit messages which span multiple lines are no problem, though only the first 10000 lines of a tag's message will be exported.
  - useMostRecentTag : boolean (optional)
- $class: 'IgnoreNotifyCommit'
  If checked, this repository will be ignored when the notifyCommit-URL is accessed regardless of if the repository matches or not.
- 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/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.
  
  Please note that this has not been tested with submodules.
  - localBranch : String
- $class: 'MessageExclusion'
  - excludedMessage : 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
    
    .*\[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.
    (?s).*FOO.*
    This example will search 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 behaviour 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.
  - 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.
    
    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.
    
    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.
- 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 master. In this scenario, on every change of integration, Jenkins will perform a merge with the master 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.
  - options
    - mergeTarget : String
      The name of the branch within the named repository to merge to, such as master.
    - fastForwardMode (optional)
      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
      
      Values: FF, FF_ONLY, NO_FF
    - mergeRemote : String (optional)
      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 (optional)
      Merge strategy selection. This feature is not fully implemented in JGIT.
      
      Values: DEFAULT, RESOLVE, RECURSIVE, OCTOPUS, OURS, SUBTREE, RECURSIVE_THEIRS
- pretestedIntegration
  - gitIntegrationStrategy
    - accumulated
      
      Accumulated Commit Strategy
      
      This strategy merges your commits with the --no-ff switch
      
      shortCommitMessage : boolean (optional)
    - ffonly
      
      Fast Forward only (--ff-only) Strategy
      
      This strategy fast-forward only using the --ff-only switch - or fails
      
      shortCommitMessage : boolean (optional)
    - squash
      
      Squashed Commit Strategy
      
      This strategy squashes all your commit on a given branch with the --squash option
  - integrationBranch : String
    What to specify
    
    The branch name must match your integration branch name. No trailing slash.
    
    Merge is performed the following way
    
    Squash commit
    
    git checkout -B <Branch name> <Repository name>/<Branch name> git merge --squash <Branch matched by git> git commit -C <Branch matched by git>
    
    Accumulated commit
    
    git checkout -B <Branch name> <Repository name>/<Branch name> git merge -m <commitMsg> <Branch matched by git> --no-ff
    
    When changes are pushed to the integration branch?
    
    Changes are only ever pushed when the build results is SUCCESS
    
    git push <Repository name> <Branch name>
  - repoName : String
    
    What to specify
    
    The repository name. In git the repository is always the name of the remote. So if you have specified a repository name in your Git configuration. You need to specify the exact same name here, otherwise no integration will be performed. We do the merge based on this.
    
    No trailing slash on repository name.
    
    Remember to specify this when working with NAMED repositories in Git
- pruneStaleBranch
  Run "git remote prune" for each remote, to prune obsolete local branches.
- pruneTags
  - pruneTags : boolean
- $class: 'RelativeTargetDirectory'
  - 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.
    This extension should not be used in Jenkins Pipeline (either declarative or scripted). Jenkins Pipeline already provides standard techniques for checkout to a subdirectory. Use ws and dir in Jenkins Pipeline rather than this extension.
- $class: 'ScmName'
  Unique name for this SCM. Needed when using Git within the Multi SCM plugin.
  - name : String
- sparseCheckout
  Specify the paths that you'd like to sparse checkout. This may be used for saving space (Think about a reference repository). Be sure to use a recent version of Git, at least above 1.7.10
  - sparseCheckoutPaths
    - path : String
- submodule
  - depth : int (optional)
    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.
  - disableSubmodules : boolean (optional)
    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.
  - parentCredentials : boolean (optional)
    Use credentials from the default remote of the parent project.
  - recursiveSubmodules : boolean (optional)
    Retrieve all submodules recursively (uses '--recursive' option which requires git>=1.6.5)
  - reference : String (optional)
    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:
    
    git init --bare git remote add SubProject1 https://gitrepo.com/subproject1 git remote add SubProject2 https://gitrepo.com/subproject2 git fetch --all
  - shallow : boolean (optional)
    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 : int (optional)
    Specify the number of threads that will be used to update submodules.
    If unspecified, the command line git default thread count is used.
  - timeout : int (optional)
    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 (see JENKINS-11286). Note that property should be set on both controller and agent to have effect (see JENKINS-22547).
  - trackingSubmodules : boolean (optional)
    Retrieve the tip of the configured branch in .gitmodules (Uses '--remote' option which requires git>=1.8.2)
- $class: 'UserExclusion'
  - 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 behaviour 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 exact string comparison and must be separated by a new line. User names are only excluded if they exactly match one of the names in this list.
    
    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'
  - name : String
    
    If given, "GIT_COMMITTER_NAME=[this]" and "GIT_AUTHOR_NAME=[this]" are set for builds. This overrides whatever is in the global settings.
  - email : String
    
    If given, "GIT_COMMITTER_EMAIL=[this]" and "GIT_AUTHOR_EMAIL=[this]" are set for builds. This overrides whatever is in the global settings.
- $class: 'WipeWorkspace'
  Delete the contents of the workspace before building, ensuring a fully fresh workspace.
doGenerateSubmoduleConfigurations : boolean (optional)
Removed facility that was intended to test combinations of git submodule versions. Removed in git plugin 4.6.0. Ignores the user provided value and always uses false as its value.
submoduleCfg (optional)
Removed facility that was intended to test combinations of git submodule versions. Removed in git plugin 4.6.0. Ignores the user provided value(s) and always uses empty values.
- submoduleName : String
  Removed in git plugin 4.6.0.
- branches : Array / List of String
  Removed in git plugin 4.6.0.

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

See existing feedback here.

User Handbook

Tutorials

Resources

scmGit

Accumulated Commit Strategy

Fast Forward only (--ff-only) Strategy

Squashed Commit Strategy

What to specify

Merge is performed the following way

Squash commit

Accumulated commit

When changes are pushed to the integration branch?

What to specify