Git credentials binding for sh, bat, and powershell

Goal: Allow greater git flexibility from Jenkins Pipelines

Status: Completed

Team

Details

Abstract

Allow Jenkins Pipeline users to run authenticated git commands in sh, bat, and powershell.

This project idea proposes to implement two new credential bindings that contribute files and environment variables to sh, bat, and powershell steps so that they can use command line git to perform authenticated operations. The Jira issue requesting support for authenticated git operations (JENKINS-28335) is one of the top five most highly voted Jenkins enhancement requests.

The two credential bindings will be gitSshPrivateKey and gitUsernamePassword. They will be implemented in the git plugin with automated tests to confirm the bindings are behaving as expected on the wide range of command line git versions and operating systems supported by the git plugin.

Rationale

The Jenkins git plugin uses Jenkins credentials to fetch a repository and checkout a branch for freestyle, pipeline, and multibranch pipeline jobs. It is also able to use Jenkins credentials to push tags and commits back to the repository from a freestyle job. It supports a wide range of command line git versions, from git 1.8.3 (CentOS 7) through the current release of command line git (2.30.0, Debian testing, Windows, …​). It supports ssh private keys with and without passphrases for ssh protocol authentication and supports usernames and passwords or API tokens for https protocol authentication.

The git plugin is not able to push tags or commits from a pipeline job or a multibranch pipeline job. It is not able to perform other git operations that require authentication like remote branch creation or deletion. The git plugin also does not provide authenticated access to all the command line options offered with the most recent versions of command line git. For example, there is no support in the git plugin for the --single-branch option or for the --recurse-submodules option.

With the git credentials binding, Pipeline users will be able to push merge results, commits, and tags from a Pipeline job. They will be able to create and delete remote branches. They will be able to use the git command line options of their choice, including --single-branch and --recurse-submodules. Users will be able to run authenticated git commands in their Jenkins Pipelines without modifying the git plugin.

Implementation

Both gitUsernamePassword and gitSshPrivateKey bindings depend on the Credential Plugin to retrieve user’s credential using the Credentials API.

The Credentials Binding Plugin is used to bind Git specific environment variables with script(sh,bat,powershell) / terminal commands depending upon the current CLI-git version installed on system which is being used to perform git operation that requires authentication.

The bindings only provide authentication support for the command line git implementation. Other Git implementations inside the git client plugin such as JGit and JGit with Apache HTTP Client are not supported. Users are provided with a dropbox which lists all the Git-Tool implementation of CLI-Git configured in Jenkins Global System Configuration.

Both the bindings works on behalf of the user to provide git authentication support, without complicated steps to pass the credentials to command line git.

NOTE

If no CLI-Git implemented Git-Tool is available in Global System Configuration then by default JGit implemented Git-Tool will be used.

Git Username and Password Binding

The gitUsernamePassword implementation uses the Jenkins username and password values retrieved through Credential API, to access a remote repository over HTTP protocol. The binding uses the GIT_ASKPASS environment variable to provide credentials requested by a git operation in a pipeline job/freestyle project. Executable script(sh,bat,powershell) is attached/bound to the GIT_ASKPASS variable, which is invoked when asked for the user’s credentials by HTTP server.

Pipeline Job

Using Git Username and Password Binding in a Pipeline Job

Git Username and Password in Pipeline Job
FreeStyle Project

Using Git Username and Password Binding in a FreeStyle-Project

Git Username and Password in FreeStyle Project
Two variable bindings GIT_USERNAME and GIT_PASSWORD provide the username and password respectively. These variable bindings are also accessible when using JGit/JGit with Apache HTTP Client Git-Tool implementations in both freestyle project and pipeline job.

Git SSH Private Key Binding

The gitSshPrivateKey implementation provides git authentication support over SSH protocol using private key and passphrase credentials of a user. The binding uses two git specific environment variables depending upon the minimum CLI-git version

  • GIT_SSH_COMMAND - If version is greater than or equal to 2.3, then the GIT_SSH_COMMAND environment variable provides the ssh command including necessary options which are: path to the private key and host key checking, to authenticate and connect to the git server without using an executable script.

  • SSH_ASKPASS - If version is less than 2.3, an executable script is attached to the variable which provides the ssh command including necessary options which are: path to the private key and host key checking, to authenticate and connect to the git server

Support for private key formats

  • The following key formats are supported through Jenkins plugins

    • BouncyCastle API Plugin - Supports decryption of PKCS#8 PEM encoded and PEM private keys.

    • SSHD Plugin - Provides a transitive dependency i.e. Apache SSHD-Core v2.7.0, which supports decryption of OpenSSH/RFC4716 formatted private keys.

Support for encryption algorithms

  • The following encryption algorithms are supported in various formats discussed above

    • RSA

    • DSA

    • ECDSA

    • ED25519

Decryption of private keys

The passphrase protected private key needs to be decrypted before it can be used to perform the git authentication operation over SSH protocol, if not decrypted then a prompt is displayed to the user asking for the passphrase of the private key being used in the current job/project, which is not an expected behaviour since the passphrase is already provided by the user through Jenkins Credential Plugin.

To tackle this issue, the BouncyCastle API plugin and SSHD plugin are used to provide decryption support for the various private formats mentioned above.

Pipeline Job

Using Git SSH Private Key in a Pipeline Job

Git SSH Private Key in Pipeline Job
FreeStyle Project

Using Git SSH Private Key Binding in a FreeStyle-Project

Git SSH Private Key in FreeStyle Project
NOTE

Unlike GitUsernamePassword binding, no variable bindings are supported by gitSshPrivateKey binding.

Office hours

The Office hours are scheduled twice a week each Wednesday and Friday at 2:00 UTC, with regular meeting notes available for anyone to read.

Links

On this page

Connect