Git username / password credentials binding

Rishabh Budhouliya July 27, 2021

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:

credentialsId: 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
gitToolName: 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.

Examples

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.

Limitations

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 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

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.

Discuss