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.
gitPush: Git PushgitScm (optional)
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:
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:
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 Jenkins platform labeler 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://github.com/jenkinsci/platformlabeler-plugin' ]
])
Argument Descriptions
userRemoteConfigs
${SUPER_PROJECT_URL}/${SUBMODULE}, rather than relying on information from .gitmodules.url : String
git clone command.
name : String
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
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
branches
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>refs/heads/<branchName>.master, feature1, ...refs/heads/<branchName>refs/heads/master, refs/heads/feature1/master, ...<remoteRepoName>/<branchName>refs/heads/<branchName>.origin/masterremotes/<remoteRepoName>/<branchName>remotes/origin/masterrefs/remotes/<remoteRepoName>/<branchName>refs/remotes/origin/master<tagName>refs/tags/<tagName> instead.git-2.3.0refs/tags/<tagName>refs/tags/git-2.3.0<commitId>5062ac843f2b947733e6a3b105977056821bd352, 5062ac84, ...${ENV_VARIABLE}${TREEISH}, refs/tags/${TAGNAME}, ...<Wildcards>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>:regexp. Regular expression syntax in branches to build will only build those branches whose names match the regular expression.:^(?!(origin/prefix)).*
origin or origin/master or origin/featureorigin/prefix or origin/prefix_123 or origin/prefix-abc:origin/release-\d{8}
origin/release-20150101origin/release-2015010 or origin/release-201501011 or origin/release-20150101-something:^(?!origin/master$|origin/develop$).*
origin/branch1 or origin/branch-2 or origin/master123 or origin/develop-123origin/master or origin/developbrowser
assemblarepoUrl : String
$class: 'BacklogGitRepositoryBrowser'repoName : String
repoUrl : String
bitbucketServerrepoUrl : String
bitbucketrepoUrl : String
cgitrepoUrl : String
fisheyerepoUrl : String
gitblitrepoUrl : String
projectName : String
$class: 'GitBucketBrowser'url : String
gitLabrepoUrl : String
version : String (optional)
$class: 'GitLabBrowser'https://gitLab.example.com then the URL for bob's skunkworks project might be https://gitLab.example.com/bob/skunkworks.
projectUrl : String
https://gitLab.example.com then the URL for bob's skunkworks project might be https://gitLab.example.com/bob/skunkworks
gitListrepoUrl : String
gitWebrepoUrl : String
$class: 'GiteaBrowser'repoUrl : String
https://gitea.example.com then the URL for bob's skunkworks project repository might be https://gitea.example.com/bob/skunkworks
githubrepoUrl : String
gitilesrepoUrl : String
$class: 'GitoriousWeb'repoUrl : String
gogsrepoUrl : String
kilnrepoUrl : String
phabricatorrepoUrl : String
repo : String
redminerepoUrl : String
rhodeCoderepoUrl : String
$class: 'ScmManagerGitRepositoryBrowser'repoUrl : String
$class: 'Stash'repoUrl : String
teamFoundationrepoUrl : String
If TFS is also used as the repository server, this can usually be left blank.
$class: 'TracGitRepositoryBrowser'$class: 'TuleapBrowser'repositoryUrl : String
viewgitrepoUrl : String
projectName : String
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:
authorInChangelog$class: 'BuildChooserSetting'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'buildSingleRevisionOnlychangelogToBranchoptions
compareRemote : String
origin, that contains the branch you specify below.
compareTarget : String
checkoutOptiontimeout : int
cleanBeforeCheckout.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)
.git directories.
cleanAfterCheckout.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)
.git directories.
cloneOptionshallow : boolean
noTags : boolean
reference : String
timeout : int
depth : int (optional)
honorRefspec : boolean (optional)
$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'$class: 'ExcludeFromChangeSet'$class: 'ExcludeFromPoll'lfs$class: 'GitSCMChecksExtension'verboseConsoleLog : boolean (optional)
$class: 'GitSCMStatusChecksExtension'name : String (optional)
skip : boolean (optional)
skipProgressUpdates : boolean (optional)
suppressLogs : boolean (optional)
unstableBuildNeutral : boolean (optional)
$class: 'GitTagMessageExtension'useMostRecentTag : boolean (optional)
$class: 'IgnoreNotifyCommit'localBranchIf 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
.*\[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'includedRegions : String
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
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$class: 'PreBuildMerge'options
mergeTarget : String
master.
fastForwardMode (optional)
FF, FF_ONLY, NO_FFmergeRemote : String (optional)
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)
DEFAULT, RESOLVE, RECURSIVE, OCTOPUS, OURS, SUBTREE, RECURSIVE_THEIRSpretestedIntegrationgitIntegrationStrategy
accumulatedshortCommitMessage : boolean (optional)
ffonlyshortCommitMessage : boolean (optional)
squashintegrationBranch : String
The branch name must match your integration branch name. No trailing slash.
git checkout -B <Branch name> <Repository name>/<Branch name>
git merge --squash <Branch matched by git>
git commit -C <Branch matched by git>
git checkout -B <Branch name> <Repository name>/<Branch name>
git merge -m <commitMsg> <Branch matched by git> --no-ff
Changes are only ever pushed when the build results is SUCCESS
git push <Repository name> <Branch name>
repoName : String
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
pruneStaleBranchpruneTagspruneTags : boolean
$class: 'RelativeTargetDirectory'relativeTargetDir : String
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
$class: 'SparseCheckoutPaths'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
submoduledepth : int (optional)
disableSubmodules : boolean (optional)
parentCredentials : boolean (optional)
recursiveSubmodules : boolean (optional)
reference : String (optional)
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)
threads : int (optional)
timeout : int (optional)
trackingSubmodules : boolean (optional)
$class: 'UserExclusion'excludedUsers : String
auto_build_userThe 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'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.
targetBranch : String (optional)
targetRepo : String (optional)
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.