Git credentials binding for sh, bat, and powershell

Project goal: Allow greater git flexibility from Jenkins Pipelines

Skills to study/improve: Java, Git

Details

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.

Quickstart

The project idea is expected to require changes in the git plugin.

Install a git plugin development environment by following the contributing instructions. Compile the plugin, run its automated tests, and confirm that the automated tests are passing. Enable coverage reporting and review the coverage report.

Install an integrated development environment (Netbeans, Eclipse, IntelliJ, …​). Run the git plugin in the development environment. Set a breakpoint and confirm that the breakpoint is reached in the development environment.

Alternately, use the coverage report to identify an interesting area that has insufficient test coverage. Submit one or more tests to improve coverage. For example, more tests could be created for MergeWithGitSCMExtension or more tests could be added to PreBuildMerge or added to UserIdentity.

Newbie-friendly issues

Consider implementing a fix for one or more of the newbie friendly issues.

Examples from that list include:

  • Add sparse checkout support to the JGit implementation (JENKINS-45368)

  • Convert git client plugin tests from JUnit 3 to JUnit 4 (JENKINS-60940)

  • Expand environment variables in sparse checkout fields (JENKINS-23477)

  • Confine git commands to workspace directory (JENKINS-38699)

Implementation examples

The sshPrivateKey and usernamePassword implementations in the credentials binding plugin provide examples that create environment variables and temporary files for use by sh, bat, and powershell steps. Use them as a reference implementation. The git credentials implementation will need environment variables for the ssh and https credentials. The git credentials implementation will need files for the ssh credentials.

The gitSshPrivateKey implementation will use the isAtLeastVersion method provided by the CliGitAPIImpl class in git client plugin, to discover the minimum CLI git version that will be used in the sh, bat, and powershell commands within the withCredentials block. If the isAtLeastVersion 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 isAtLeastVersion 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.

The gitUsernamePassword implementation should use the Jenkins username and password values to configure a git credential based on the git-credential documentation.

Potential Mentors

Project Links

Organization Links

> Go back to other GSoC 2021 project ideas