Git Client Plugin for Jenkins

The Git Client Plugin provides Git APIs for Jenkins plugins, enabling operations such as fetching, checking out, branching, listing, merging, and tagging repositories.

It supports:

• HTTP/HTTPS: Username/password credentials (e.g., https://github.com/user/repo.git).
• SSH: Private key credentials (e.g., git@github.com:user/repo.git or ssh://git@github.com/user/repo.git).

Credential management is handled via the Jenkins Credentials Plugin.

The two implementations handle timeouts differently:

• Command Line Git: Uses a high-level operation timeout. The timer starts at the beginning of the command and is not reset. If the operation exceeds this time, the process is canceled.
• JGit: Uses a network-level transport timeout. The timer is reset every time a response is received from the remote server. This prevents JGit from hanging indefinitely if a server stops responding, but it does not cap the total execution time of a single operation.

The plugin offers different implementations for Git operations:

1. Command Line Git (Default): The canonical implementation. Requires git to be installed on the Jenkins controller and all agents. For large file support, install git LFS.
2. JGit (Optional): A pure Java implementation using Eclipse JGit. It is disabled by default. It provides most command-line functionality, but gaps are noted in console logs.
3. JGit with Apache HTTP Client (Optional): A version of JGit that uses Apache HTTP client for authentication, primarily maintained for compatibility with specific authentication scenarios.

The plugin uses the Java Microbenchmark Harness (JMH) to compare the performance of command-line git versus JGit.

To run the benchmarks, use:

mvn -P jmh-benchmark -Dbenchmark.run=true test

After running, you can visualize the results by pasting the generated jmh-report.json file into the online JMH visualizer.

The project uses the spotless Maven plugin to maintain formatting for source code and pom.xml files. Run the following command to apply the correct formatting before submitting a pull request.

mvn spotless:apply

To compile the plugin and run automated tests, use Java 11 or Java 17. Ensure you have Maven installed.

mvn clean verify

To use JGit instead of the command-line implementation:

1. Navigate to Manage Jenkins >> Tools.
2. Click the Add Git button.
3. Select either JGit or JGit with Apache HTTP Client.

Use Spotbugs to check for potential bugs in the source code. You should ensure that your pull request does not introduce new Spotbugs warnings.

To run the check:

mvn spotbugs:check

To review the report using a GUI:

mvn spotbugs:gui

You can run the plugin locally within a Jenkins environment using the maven hpi plugin. This is useful for manual testing of the plugin's behavior in a live Jenkins instance.

mvn -Djetty.port=8080 hpi:run

Jenkins can automatically install MinGit (a minimal, non-interactive Git for Windows distribution) on Windows agents. To configure this:

1. Go to Manage Jenkins >> Tools.
2. Configure a global git tool with the following settings:
   • Name: (e.g., git)
   • Path to Git executable: git
   • Label: windows (to limit installation to Windows agents)
   • Download URL for binary archive: The URL to your locally hosted MinGit zip file.
   • Subdirectory of extracted archive: mingw64\bin\git.exe

MinGit will be installed at tools\git\mingw64 and the executable will be located at tools\git\mingw64\bin\git.exe.

To test a specific Pull Request (PR) build, follow these steps:

1. Find the PR on GitHub: Locate the target pull request (e.g., https://github.com/jenkinsci/git-client-plugin/pull/467).
2. Locate Artifacts: Find the link to the ci.jenkins.io artifacts for that PR. This is typically found under "Show all checks" in the Jenkins job link (e.g., https://ci.jenkins.io/job/Plugins/job/git-client-plugin/view/change-requests/...).
3. Download the .hpi file: Download the plugin artifact (e.g., git-client-3.0.1-rc3444.b3d767e3d46a.hpi).
4. Upload to Jenkins: Use the Jenkins Plugin Manager to upload the .hpi file to your local or test Jenkins instance.
5. Restart Jenkins: Restart the Jenkins service to complete the installation and begin testing.

To ensure your changes meet coverage requirements, use the JaCoCo profile to generate a report.

mvn -P enable-jacoco clean install jacoco:report