Goal: Allow greater git flexibility from Jenkins Pipelines
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
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.
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
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
Users will be able to run authenticated git commands in their Jenkins Pipelines without modifying the git plugin.
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 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.
If no CLI-Git implemented Git-Tool is available in
Global System Configuration then by default JGit
implemented Git-Tool will be used.
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.
Using Git Username and Password Binding in a Pipeline Job
Using Git Username and Password Binding in a FreeStyle-Project
Two variable bindings
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
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.
Using Git SSH Private Key in a Pipeline Job
Using Git SSH Private Key Binding in a FreeStyle-Project
Unlike GitUsernamePassword binding, no variable bindings are supported by gitSshPrivateKey binding.
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.
Jenkins GSoC mailing list discussion of git credentials pipeline task
JENKINS-28335 - Pipeline step to run Git commands with credentials & tool
JENKINS-47733 - Add a
withGit pipeline step that provides git credentials
JENKINS-36496 - Support git publisher with Pipeline