Git credentials binding for sh, bat, and powershell

Goal: Allow greater git flexibility from Jenkins Pipelines

Status: Active

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 use 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 programs to perform authentication on behalf of the user, without their interaction with the command-line.

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. This binding uses the GIT_ASKPASS environment variable to provide credentials requested by command line git. The program specified by this variable is invoked with a suitable prompt on the command-line, and the user’s credential are read from its standard output.

Git Username and Password
By default, two variable bindings GIT_USERNAME and GIT_PASSWORD, bind with user’s credential i.e. username and password respectively. These variable bindings are available in both freestyle project and pipeline script.

The gitUsernamePassword binding only provides authentication support for the Git CLI implementation. Other Git implementations inside the git client plugin such as JGit and JGit with Apache HTTP Client are not supported.

Git SSH Private Key Binding

The gitSshPrivateKey implementation uses isAtLeastVersion method provided by CliGitAPIImpl to discover the minimum CLI git version that will be used in the sh, bat, and powershell commands within the withCredentials block. If the cliGitBaseVersion is greater than 2.3, then the GIT_SSH_COMMAND environment variable should be set and should include arguments that provide the path to the private key. If the cliGitBaseVersion is less than 2.3, then the current ssh technique in the git plugin should be used instead (needs more details of the current technique). The SSH_ASKPASS environment variable should be set to point to a file that is accessible to the agent workspace. That SSH_ASKPASS script should echo the passphrase if a passphrase is defined on the private key, just as is done today within the git plugin. The credential binding should write the ssh private key to the agent file system in a workspace specific temporary location and should set environment variables to provide the location of the ssh private key. Alternately, passphrase protected private keys should be converted by the plugin to not use a passphrase and the private key without passphrase should be written to the workspace specific temporary location instead of writing the private key with passphrase.

Office hours

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

Links