Back to blog

Git username / password credentials binding

Mark Waite
Mark Waite
Rishabh Budhouliya
Rishabh Budhouliya
July 27, 2021

Git username/password credentials binding

Google Summer of Code 2021 is implementing git credentials binding for sh, bat, and powershell. Git credentials binding is one of the most requested features for Jenkins Pipeline (see JENKINS-28335).

The project involves extending the Credentials Binding Plugin to create custom bindings for two types of credentials essential to establish a remote connection with a git repository

  • Username/Password

  • SSH Private Key

Why use git credentials binding?

Many operations in a Jenkins Pipeline or Freestyle job can benefit from authenticated access to git repositories. Authenticated access to a git repository allows a Jenkins job to

  • apply a tag and push the tag

  • merge a commit and push the merge

  • update submodules from private repositories

  • retrieve large files with git LFS

The git credentials username / password binding included in git plugin 4.8.0 allows Pipeline and Freestyle jobs to use command line git from sh, bat, and powershell for authenticated access to git repositories.

How to use git credentials binding?

The binding is accessible using the withCredentials Pipeline step. It requires two parameters:


Reference id provided by creating a Username/Password type credential in the Jenkins configuration. To understand how to configure credentials in a Jenkins environment: Using Credentials


Name of the git installation in the machine running the Jenkins instance (Check Global Tool Configuration section in Jenkins UI)

Note: In case a user is not aware of the git tool installation of the particular machine, the default git installation will be chosen.


The withCredentials wrapper allows declarative and scripted Pipeline jobs to perform authenticated command line git operations with sh, bat, and powershell tasks.

Shell example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) {
  sh 'git fetch --all'
Batch example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) {
  bat 'git submodule update --init --recursive'
Powershell example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) {
  powershell 'git push'

The Pipeline Syntax Snippet Generator is a good way to explore the syntax of the withCredentials step and the git username / password credentials binding.


The git credentials username / password binding has been tested on command line git versions 1.8.3 through 2.32.0. It has been tested on CentOS 7, CentOS 8, Debian 9, Debian 10, FreeBSD 12, OpenBSD 6.9, openSUSE 15.2, Ubuntu 18.04, Ubuntu 20.04, Ubuntu 21.04, and Windows 10. Processor testing has included amd64, arm32, arm64, and s390x.

The binding does not support private key credentials. The binding is not supported on command line git versions prior to 1.8.3.

What’s next?

Private key credentials support is coming soon.

About the authors

Mark Waite

Mark Waite

Mark is a member of the Jenkins governing board, a long-time Jenkins user and contributor, a core maintainer, and maintainer of the git plugin, the git client plugin, the platform labeler plugin, the embeddable build status plugin, and several others. He is one of the authors of the "Improve a plugin" tutorial.

Rishabh Budhouliya

Rishabh Budhouliya

GSoC 2020 student under the Jenkins project (Git Plugin Performance Improvements). Aspiring to be better at Software Development and participate more in the open source community.