Git username / password credentials binding

Published on 2021-07-27 by Mark Waite, Rishabh Budhouliya

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:

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 the Jenkins Documentation Officer, a long-time Jenkins user and contributor, and maintains the git plugin and the git client plugin. He is active in Jenkins special interest groups including the Docs SIG, Platform SIG, and Advocacy SIG.
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