Merge remote-tracking branch 'upstream/master' as of 2025-01-16 into …

…refrepo-args

Signed-off-by: Evgeny Klimov <[email protected]>

.gitattributes

@@ -1,7 +1,11 @@
+*.adoc text eol=lf
+*.config text eol=lf
 *.html text eol=lf
+*.in text eol=lf
 *.java text eol=lf
 *.jelly text eol=lf
-*.md text eol=lf
+*.properties text eol=lf
 *.sh text eol=lf
 *.xml text eol=lf
+*.yaml text eol=lf
 *.yml text eol=lf

README.adoc

@@ -102,7 +102,7 @@ By default, Git Client plugin uses the "Known hosts file" strategy to verify all
 Host key verification strategies include:
 
 Accept first connection::
-Remembers the first host key encountered for each git server and requires that the same host key must be use for later access.
+Remembers the first host key encountered for each git server and requires that the same host key must be used for later access.
 This is usually the most convenient setting for administrators while still providing ssh host key verification
 
 Known hosts file::

pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>org.jenkins-ci.plugins</groupId>
     <artifactId>plugin</artifactId>
-    <version>5.2</version>
+    <version>5.5</version>
     <relativePath />
   </parent>
 
@@ -24,27 +24,6 @@
     </license>
   </licenses>
 
-  <developers>
-    <developer>
-      <id>markewaite</id>
-      <name>Mark Waite</name>
-      <email>[email protected]</email>
-    </developer>
-    <developer>
-      <id>rsandell</id>
-      <name>Robert Sandell</name>
-      <email>[email protected]</email>
-      <url>http://rsandell.com</url>
-    </developer>
-    <developer>
-      <id>olamy</id>
-      <name>Olivier Lamy</name>
-      <email>[email protected]</email>
-      <url>https://about.me/olamy</url>
-      <timezone>Australia/Brisbane</timezone>
-    </developer>
-  </developers>
-
   <scm>
     <connection>scm:git:https://github.com/${gitHubRepo}</connection>
     <developerConnection>scm:git:[email protected]:${gitHubRepo}.git</developerConnection>
@@ -72,7 +51,7 @@
       <dependency>
         <groupId>io.jenkins.tools.bom</groupId>
         <artifactId>bom-${jenkins.baseline}.x</artifactId>
-        <version>3559.vb_5b_81183b_d23</version>
+        <version>3893.v213a_42768d35</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
@@ -212,7 +191,7 @@
     <dependency>
       <groupId>io.github.sparsick.testcontainers.gitserver</groupId>
       <artifactId>testcontainers-gitserver</artifactId>
-      <version>0.10.0</version>
+      <version>0.11.0</version>
       <scope>test</scope>
       <exclusions>
         <exclusion>
@@ -234,7 +213,7 @@
     <dependency>
       <groupId>nl.jqno.equalsverifier</groupId>
       <artifactId>equalsverifier</artifactId>
-      <version>3.17.1</version>
+      <version>3.18.1</version>
       <scope>test</scope>
     </dependency>
     <dependency>
@@ -270,7 +249,7 @@
     <dependency>
       <groupId>org.testcontainers</groupId>
       <artifactId>testcontainers</artifactId>
-      <version>1.20.3</version>
+      <version>1.20.4</version>
       <scope>test</scope>
     </dependency>
   </dependencies>
@@ -291,13 +270,28 @@
 
   <build>
     <plugins>
+      <plugin>
+        <!-- Needed by the mockito-core properties reference in surefire -->
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <executions>
+          <execution>
+            <goals>
+              <goal>properties</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>
         <configuration>
           <systemPropertyVariables>
             <org.jenkinsci.plugins.gitclient.verifier.SshHostKeyVerificationStrategy.jgit_known_hosts_file>${project.build.directory}/ssh/know_hosts</org.jenkinsci.plugins.gitclient.verifier.SshHostKeyVerificationStrategy.jgit_known_hosts_file>
           </systemPropertyVariables>
+          <!-- Add mockito javaagent for the MockitoJUnitRunner in Java 21 and beyond -->
+          <!-- https://javadoc.io/doc/org.mockito/mockito-core/latest/org/mockito/Mockito.html#0.3 -->
+          <argLine>@{argLine} -javaagent:${org.mockito:mockito-core:jar}</argLine>
         </configuration>
       </plugin>
       <plugin>

src/main/java/org/jenkinsci/plugins/gitclient/CliGitAPIImpl.java

@@ -21,6 +21,7 @@
 import hudson.plugins.git.IGitAPI;
 import hudson.plugins.git.IndexEntry;
 import hudson.plugins.git.Revision;
+import hudson.slaves.WorkspaceList;
 import hudson.util.ArgumentListBuilder;
 import hudson.util.Secret;
 import java.io.*;
@@ -2092,7 +2093,8 @@ Path createTempFile(String prefix, String suffix) throws IOException {
         if (workspace == null) {
             return createTempFileInSystemDir(prefix, suffix);
         }
-        File workspaceTmp = new File(workspace.getAbsolutePath() + "@tmp");
+
+        File workspaceTmp = new File(workspace.getAbsolutePath() + WorkspaceList.TMP_DIR_SUFFIX);
         if (!workspaceTmp.isDirectory() && !workspaceTmp.mkdirs()) {
             if (!workspaceTmp.isDirectory()) {
                 return createTempFileInSystemDir(prefix, suffix);

src/main/java/org/jenkinsci/plugins/gitclient/verifier/AcceptFirstConnectionStrategy.java

@@ -5,13 +5,24 @@
 import hudson.model.Descriptor;
 import org.kohsuke.stapler.DataBoundConstructor;
 
+/**
+ * Accept known hosts strategy for the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}.
+ *
+ * <p>Remembers the first host key encountered for each git server and requires that the same host key must be used for later access.
+ * This is usually the most convenient setting for administrators while still providing ssh host key verification
+ */
 public class AcceptFirstConnectionStrategy extends SshHostKeyVerificationStrategy<AcceptFirstConnectionVerifier> {
 
+    /**
+     * Creates a secure shell host key verification strategy that accepts known hosts on first connection.
+     * Remembers the first host key encountered for each git server and requires that the same host key must be used for later access.
+     */
     @DataBoundConstructor
     public AcceptFirstConnectionStrategy() {
         // stapler needs @DataBoundConstructor
     }
 
+    /** {@inheritDoc} */
     @Override
     public AcceptFirstConnectionVerifier getVerifier() {
         return new AcceptFirstConnectionVerifier();

src/main/java/org/jenkinsci/plugins/gitclient/verifier/KnownHostsFileVerificationStrategy.java

@@ -5,13 +5,24 @@
 import hudson.model.Descriptor;
 import org.kohsuke.stapler.DataBoundConstructor;
 
+/**
+ * Known hosts strategy for the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}.
+ *
+ * <p>Uses the existing 'known_hosts' file on the controller and on the agent.
+ * This assumes the administrator has already configured this file on the controller and on all agents
+ */
 public class KnownHostsFileVerificationStrategy extends SshHostKeyVerificationStrategy<KnownHostsFileVerifier> {
 
+    /**
+     * Creates a secure shell host key verification strategy that uses the existing 'known_hosts' file on the controller and on the agent.
+     * This assumes the administrator has already configured this file on the controller and on all agents
+     */
     @DataBoundConstructor
     public KnownHostsFileVerificationStrategy() {
         // stapler needs @DataBoundConstructor
     }
 
+    /** {@inheritDoc} */
     @Override
     public KnownHostsFileVerifier getVerifier() {
         return new KnownHostsFileVerifier();

src/main/java/org/jenkinsci/plugins/gitclient/verifier/ManuallyProvidedKeyVerificationStrategy.java

@@ -8,21 +8,36 @@
 import org.kohsuke.stapler.DataBoundConstructor;
 import org.kohsuke.stapler.QueryParameter;
 
+/**
+ * Manually provided host key strategy for the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}.
+ *
+ * <p>Provides a form field where the administrator inserts the host keys for the git repository servers.
+ * This works well when a small set of repository servers meet the needs of most users
+ */
 public class ManuallyProvidedKeyVerificationStrategy
         extends SshHostKeyVerificationStrategy<ManuallyProvidedKeyVerifier> {
 
     private final String approvedHostKeys;
 
+    /**
+     * Creates a secure shell host key verification strategy that uses the host keys provided by the Jenkins administrator.
+     * This works well when a small set of repository servers meet the needs of most users
+     */
     @DataBoundConstructor
     public ManuallyProvidedKeyVerificationStrategy(String approvedHostKeys) {
         this.approvedHostKeys = approvedHostKeys.trim();
     }
 
+    /** {@inheritDoc} */
     @Override
     public ManuallyProvidedKeyVerifier getVerifier() {
         return new ManuallyProvidedKeyVerifier(approvedHostKeys);
     }
 
+    /**
+     * Returns the approved host keys.
+     * @return approved host keys
+     */
     public String getApprovedHostKeys() {
         return approvedHostKeys;
     }
@@ -42,6 +57,7 @@ public FormValidation doCheckApprovedHostKeys(@QueryParameter String approvedHos
         }
     }
 
+    /** {@inheritDoc} */
     @Override
     public boolean equals(Object o) {
         if (this == o) {
@@ -54,6 +70,7 @@ public boolean equals(Object o) {
         return Objects.equals(approvedHostKeys, that.approvedHostKeys);
     }
 
+    /** {@inheritDoc} */
     @Override
     public int hashCode() {
         return Objects.hash(approvedHostKeys);

src/main/java/org/jenkinsci/plugins/gitclient/verifier/NoHostKeyVerifier.java

@@ -5,10 +5,20 @@
 import java.util.logging.Logger;
 import org.eclipse.jgit.transport.sshd.ServerKeyDatabase;
 
+/**
+ * Disable all host key verification by the {@link SshHostKeyVerificationStrategy host key verification strategy extension point}.
+ *
+ * <p>Disables all verification of ssh host keys.
+ * <strong>Not recommended</strong> because it provides no protection from "man-in-the-middle" attacks
+ */
 public class NoHostKeyVerifier extends HostKeyVerifierFactory {
 
     private static final Logger LOGGER = Logger.getLogger(NoHostKeyVerifier.class.getName());
 
+    /**
+     * Creates a secure shell host key verification strategy that performs no host key verification.
+     * <strong>Not recommended</strong> because it provides no protection from "man-in-the-middle" attacks.
+     */
     @Override
     public AbstractCliGitHostKeyVerifier forCliGit(TaskListener listener) {
         return tempKnownHosts -> "-o StrictHostKeyChecking=no";

src/main/java/org/jenkinsci/plugins/gitclient/verifier/SshHostKeyVerificationStrategy.java

@@ -8,21 +8,72 @@
 import jenkins.model.Jenkins;
 import org.apache.commons.lang.StringUtils;
 
+/**
+ * Secure shell host key verification strategy extension point for SSH connections from the git client plugin.
+ * Secure shell (ssh) host key verification protects an SSH client from a
+ * <a href="https://superuser.com/questions/1657387/how-does-host-key-checking-prevent-man-in-the-middle-attack">man in the middle attack</a>.
+ *
+ * <p>Host key verifications strategies allow the Jenkins administrator
+ * to choose the level of host key verification that will be
+ * performed.
+ *
+ * <p>Host key verification strategies include:
+ *
+ * <dl>
+ * <dt>{@link AcceptFirstConnectionStrategy Accept first connection}</dt>
+ * <dd>
+ * Remembers the first host key encountered for each git server and requires that the same host key must be used for later access.
+ * This is usually the most convenient setting for administrators while still providing ssh host key verification
+ * </dd>
+ *
+ * <dt>{@link KnownHostsFileVerificationStrategy Known hosts file}</dt>
+ * <dd>
+ * Uses the existing 'known_hosts' file on the controller and on the agent.
+ * This assumes the administrator has already configured this file on the controller and on all agents
+ * </dd>
+ *
+ * <dt>{@link ManuallyProvidedKeyVerifier Manually provided keys}</dt>
+ * <dd>
+ * Provides a form field where the administrator inserts the host keys for the git repository servers.
+ * This works well when a small set of repository servers meet the needs of most users
+ * </dd>
+ *
+ * <dt>{@link NoHostKeyVerificationStrategy No verification}</dt>
+ * <dd>
+ * Disables all verification of ssh host keys.
+ * <strong>Not recommended</strong> because it provides no protection from "man-in-the-middle" attacks
+ * </dd>
+ * </dl>
+ *
+ * Configure the host key verification strategy from "Manage Jenkins" / "Security" / "Git Host Key Verification Configuration".
+ * More details are available in the <a href="https://plugins.jenkins.io/git-client/#plugin-content-ssh-host-key-verification">plugin documentation</a>.
+ */
 public abstract class SshHostKeyVerificationStrategy<T extends HostKeyVerifierFactory>
         extends AbstractDescribableImpl<SshHostKeyVerificationStrategy<T>> implements ExtensionPoint {
 
+    /** Default path to the known hosts file for the current user. */
     public static final String KNOWN_HOSTS_DEFAULT =
             Path.of(System.getProperty("user.home"), ".ssh", "known_hosts").toString();
+
     private static final String JGIT_KNOWN_HOSTS_PROPERTY =
             SshHostKeyVerificationStrategy.class.getName() + ".jgit_known_hosts_file";
     private static final String JGIT_KNOWN_HOSTS_FILE_PATH =
             StringUtils.defaultIfBlank(System.getProperty(JGIT_KNOWN_HOSTS_PROPERTY), KNOWN_HOSTS_DEFAULT);
+    /** JGit known hosts file path for the current user.
+     * Uses the {@link #KNOWN_HOSTS_DEFAULT default path} to the known hosts file for the current user
+     * unless the <code>JGIT_KNOWN_HOSTS_PROPERTY</code> property is
+     * set.
+     */
     public static final File JGIT_KNOWN_HOSTS_FILE = new File(JGIT_KNOWN_HOSTS_FILE_PATH);
 
     @Override
     public Descriptor<SshHostKeyVerificationStrategy<T>> getDescriptor() {
         return (Descriptor<SshHostKeyVerificationStrategy<T>>) Jenkins.get().getDescriptorOrDie(getClass());
     }
 
+    /**
+     * Returns the ssh host key verifier for this strategy.
+     * @return ssh host key verifier for this strategy.
+     */
     public abstract T getVerifier();
 }

src/test/java/org/jenkinsci/plugins/gitclient/GitAPITest.java

@@ -87,7 +87,6 @@ public class GitAPITest {
 
     private GitClient testGitClient;
     private File testGitDir;
-    private CliGitCommand cliGitCommand;
 
     public GitAPITest(final String gitImplName) {
         this.gitImplName = gitImplName;
@@ -167,7 +166,6 @@ public void setUpRepositories() throws Exception {
 
         testGitClient = workspace.getGitClient();
         testGitDir = workspace.getGitFileDir();
-        cliGitCommand = workspace.getCliGitCommand();
         workspace.initializeWorkspace();
     }
 
@@ -760,7 +758,26 @@ public void testListRemoteBranches() throws Exception {
         workspace.launchCommand("git", "fetch", "origin");
         Set<Branch> branches = testGitClient.getRemoteBranches();
         assertBranchesExist(branches, "origin/" + defaultBranchName, "origin/test", "origin/another");
-        assertEquals(3, branches.size());
+        int branchCount = 3;
+        if (workspace.cgit().isAtLeastVersion(2, 48, 0, 0)) {
+            /* Fetch from CLI git 2.48.0 and later return origin/HEAD
+             *
+             * https://github.blog/open-source/git/highlights-from-git-2-48/ says:
+             *
+             * With Git 2.48, if the remote has a default branch but refs/remotes/origin/HEAD
+             * is missing locally, then a fetch will update it.
+             *
+             * This test was unintentionally testing the behavior of CLI git before
+             * 2.48.0.  Other tests in GitClientFetchTest were testing that origin/HEAD
+             * was reported as a branch.
+             */
+            assertBranchesExist(branches, "origin/HEAD");
+            branchCount = 4;
+        }
+        assertEquals(
+                "Wrong branch count, found " + branches.size() + " branches: " + branches,
+                branchCount,
+                branches.size());
     }
 
     @Test

src/test/java/org/jenkinsci/plugins/gitclient/GitClientSecurityTest.java

@@ -225,7 +225,6 @@ public void setGitClient() throws Exception {
         "https://github.com/jenkinsci/archetypes.git",
         "https://git.assembla.com/git-plugin.3.git",
         "https://[email protected]/markewaite/jenkins-pipeline-utils.git",
-        "https://jenkins-git-plugin.git.beanstalkapp.com/git-client-plugin.git",
         "https://gitlab.com/MarkEWaite/git-client-plugin.git",
         "origin"
     };