[JENKINS-74913] Allow extension point in bitbucket source plugin to provide a implementation for web-hooks management

Add extension point interface to register hook processor provided by other plugins
Remove manage of hook events that does ship any king of changes in the source code like reviewer changed or PR approved, they was used only to trigger builds if that kind of changes was enabled bitbucket side.
Reindex on empty changes has been turn-off by default, this to avoid scan all repositories if not required.
Remove support for version of Bitbucket Server declared in EOS by Atlassian (see https://confluence.atlassian.com/support/atlassian-end-of-support-policy-201851003.html)

Author: nfalco79

docs/USER_GUIDE.adoc

@@ -328,12 +328,12 @@ System.setProperty("http.socket.timeout", "300") // 5 minutes
 In case Bitbucket has been configured to expire OAuth2 tokens before 5 minutes, you can configure via a JVM property the release time of the cache where all obtained OAuth2 tokens are stored. This setting is to avoid requests with expired tokens that will produce HTTP 401 responses. link:https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/[Bitbucket Cloud] access tokens expire in two hours.
 To change this amount of time (default is 300 seconds), add the system property `bitbucket.oauth2.cache.timeout=60` on Jenkins startup.
 
-=== Disable Branch Indexing on Empty changes
+=== Enable Branch Indexing on Empty changes
 
-By default, the plugin triggers *a full branch indexing* when a push event contains *empty* changes. This may happen on various scenario, mainly in Bitbucket Data Center, such as:
+By default, the plugin does not triggers *a full branch indexing* when a push event contains *empty* changes. This may happen on various scenario, mainly in Bitbucket Data Center, such as:
 
 * When manually merging remote **Open** pull requests. This particular scenario produces 2 events and cause duplicated builds.
 * For a fork, when link:https://confluence.atlassian.com/bitbucketserver/keeping-forks-synchronized-776639961.html[Auto-Sync] is on and a branch cannot be synchronised
 * A link:http://confluence.atlassian.com/bitbucketserver/event-payload-938025882.html#Eventpayload-Mirrorsynchronized[mirror:repo_synchronized] event with too many refs
 
-This behaviour can be disabled by adding the system property `bitbucket.hooks.processor.scanOnEmptyChanges=false` on Jenkins startup.
+This behaviour can be enabled by adding the system property `bitbucket.hooks.processor.scanOnEmptyChanges=true` on Jenkins startup.

pom.xml

@@ -83,6 +83,10 @@
             <groupId>io.jenkins.plugins</groupId>
             <artifactId>commons-lang3-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.jenkins.plugins</groupId>
+            <artifactId>commons-collections4-api</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.jenkins-ci.plugins</groupId>
             <artifactId>jackson2-api</artifactId>

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/BitbucketException.java

@@ -24,6 +24,7 @@
 package com.cloudbees.jenkins.plugins.bitbucket.api;
 
 public class BitbucketException extends RuntimeException {
+    private static final long serialVersionUID = 1L;
 
     public BitbucketException(String message, Throwable cause) {
         super(message, cause);
@@ -33,6 +34,4 @@ public BitbucketException(String message) {
         super(message);
     }
 
-    private static final long serialVersionUID = 1L;
-
 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/hook/BitbucketHookProcessor.java

@@ -0,0 +1,151 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025, Falco Nikolas
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.cloudbees.jenkins.plugins.bitbucket.api.hook;
+
+import com.cloudbees.jenkins.plugins.bitbucket.BitbucketSCMSource;
+import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import hudson.ExtensionPoint;
+import jakarta.servlet.http.HttpServletRequest;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+import jenkins.scm.api.SCMEvent;
+import jenkins.scm.api.SCMHeadEvent;
+import jenkins.util.SystemProperties;
+import org.apache.commons.collections4.MultiValuedMap;
+import org.kohsuke.accmod.Restricted;
+import org.kohsuke.accmod.restrictions.Beta;
+
+/**
+ * Implementations of this extension point must provide new behaviours to
+ * accommodate custom event payloads from webhooks sent from Bitbucket Cloud,
+ * Bitbucket Data Center, or installed plugins.
+ * <p>
+ * There cannot be multiple processors processing the same incoming webhook for
+ * a specific event installed on the system, meaning the processor must fit to
+ * the incoming request as much as possible or the hook will be rejected.
+ */
+@Restricted(Beta.class)
+public interface BitbucketHookProcessor extends ExtensionPoint {
+    static final String SCAN_ON_EMPTY_CHANGES_PROPERTY_NAME = "bitbucket.hooks.processor.scanOnEmptyChanges";
+
+    /**
+     * Called by first for this processor that must respond if is able to handle
+     * this specific request
+     *
+     * @param headers request
+     * @param parameters request
+     * @return {@code true} if this processor is able to handle this hook
+     *         request, {@code false} otherwise.
+     */
+    boolean canHandle(@NonNull Map<String, String> headers, @NonNull MultiValuedMap<String, String> parameters);
+
+    /**
+     * Extracts the server URL from where this request coming from, the URL must
+     * match one of the configured {@link BitbucketEndpoint}s.
+     *
+     * @param headers request
+     * @param parameters request
+     * @return the URL of the server from where this request has been sent.
+     */
+    @NonNull
+    String getServerURL(@NonNull Map<String, String> headers, @NonNull MultiValuedMap<String, String> parameters);
+
+    /**
+     * Extracts the event type that represent the payload in the request.
+     *
+     * @param headers request
+     * @param parameters request
+     * @return the event type key.
+     */
+    @NonNull
+    String getEventType(Map<String, String> headers, MultiValuedMap<String, String> parameters);
+
+    /**
+     * Returns a context for a given request used when process the payload.
+     *
+     * @param request hook
+     * @return a map of information extracted by the given request to be used in
+     *         the {@link #process(String, String, Map, BitbucketEndpoint)}
+     *         method.
+     */
+    @NonNull
+    default Map<String, Object> buildHookContext(@NonNull HttpServletRequest request) {
+        return Map.of("origin", SCMEvent.originOf(request));
+    }
+
+    /**
+     * The implementation must verify if the incoming request is secured or not
+     * eventually gather some settings from the given {@link BitbucketEndpoint}
+     * configuration.
+     *
+     * @param headers request
+     * @param payload request
+     * @param endpoint configured for the given
+     *        {@link #getServerURL(Map, MultiValuedMap)}
+     * @throws BitbucketHookProcessorException when signature verification fails
+     */
+    void verifyPayload(@NonNull Map<String, String> headers,
+                       @NonNull String payload,
+                       @NonNull BitbucketEndpoint endpoint) throws BitbucketHookProcessorException;
+
+    /**
+     * Settings that will trigger a re-index of the multibranch
+     * project/organization folder when the request does not ship any source
+     * changes.
+     *
+     * @return if should perform a reindex of the project or not.
+     */
+    default boolean reindexOnEmptyChanges() {
+        return SystemProperties.getBoolean(SCAN_ON_EMPTY_CHANGES_PROPERTY_NAME, false);
+    }
+
+    /**
+     * See <a href="https://confluence.atlassian.com/bitbucket/event-payloads-740262817.html">Event
+     * Payloads</a> for more information about the payload parameter format.
+     *
+     * @param eventType the type of hook event.
+     * @param payload the hook payload
+     * @param context build from incoming request
+     * @param endpoint configured in the Jenkins global page
+     */
+    void process(@NonNull String eventType, @NonNull String payload, @NonNull Map<String, Object> context, @NonNull BitbucketEndpoint endpoint);
+
+    /**
+     * Implementations have to call this method when want propagate an
+     * {@link SCMHeadEvent} to the scm-api.
+     *
+     * @param event the to fire
+     * @param delaySeconds a delay in seconds to wait before propagate the
+     *        event. If the given value is less than 0 than default will be
+     *        used.
+     */
+    default void notifyEvent(SCMHeadEvent<?> event, int delaySeconds) {
+        if (delaySeconds == 0) {
+            SCMHeadEvent.fireNow(event);
+        } else {
+            SCMHeadEvent.fireLater(event, delaySeconds > 0 ? delaySeconds : BitbucketSCMSource.getEventDelaySeconds(), TimeUnit.SECONDS);
+        }
+    }
+}

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/hooks/NativeServerPingHookProcessor.java renamed to src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/hook/BitbucketHookProcessorException.java

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  *
- * Copyright (c) 2016-2018, Yieldlab AG
+ * Copyright (c) 2025, Falco Nikolas
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -21,23 +21,21 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.cloudbees.jenkins.plugins.bitbucket.hooks;
+package com.cloudbees.jenkins.plugins.bitbucket.api.hook;
 
-import hudson.RestrictedSince;
-import java.util.logging.Level;
-import java.util.logging.Logger;
-import org.kohsuke.accmod.Restricted;
-import org.kohsuke.accmod.restrictions.NoExternalUse;
+import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketException;
 
-@Restricted(NoExternalUse.class)
-@RestrictedSince("933.3.0")
-public class NativeServerPingHookProcessor extends HookProcessor {
+public class BitbucketHookProcessorException extends BitbucketException {
+    private static final long serialVersionUID = 6682700868741672883L;
+    private final int httpCode;
 
-    private static final Logger LOGGER = Logger.getLogger(NativeServerPingHookProcessor.class.getName());
+    public BitbucketHookProcessorException(int httpCode, String message) {
+        super(message);
+        this.httpCode = httpCode;
+    }
 
-    @Override
-    public void process(HookEventType hookEvent, String payload, BitbucketType instanceType, String origin) {
-        LOGGER.log(Level.INFO, "Received webhook ping event from {0}", origin);
+    public int getHttpCode() {
+        return httpCode;
     }
 
 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/filesystem/BitbucketSCMFileSystem.java

@@ -31,10 +31,8 @@
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketApiFactory;
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketAuthenticator;
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketCommit;
-import com.cloudbees.jenkins.plugins.bitbucket.impl.endpoint.BitbucketServerEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketApiUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.DateUtils;
-import com.cloudbees.jenkins.plugins.bitbucket.server.BitbucketServerVersion;
 import com.cloudbees.plugins.credentials.CredentialsMatchers;
 import com.cloudbees.plugins.credentials.CredentialsProvider;
 import com.cloudbees.plugins.credentials.common.StandardCredentials;
@@ -293,13 +291,7 @@ public SCMFileSystem build(@NonNull SCMSource source, @NonNull SCMHead head, @Ch
                     // Bitbucket server v7 doesn't have the `merge` ref for PRs
                     // We don't return `ref` when working with v7
                     // so that pipeline falls back to heavyweight checkout properly
-                    boolean ligthCheckout = BitbucketServerEndpoint.findServerVersion(serverURL) != BitbucketServerVersion.VERSION_7;
-                    if (ligthCheckout) {
-                        ref = "pull-requests/" + prHead.getId() + "/merge";
-                    } else {
-                        // returning null to fall back to heavyweight checkout
-                        return null;
-                    }
+                    return null;
                 }
             } else if (head instanceof BitbucketTagSCMHead) {
                 ref = "tags/" + head.getName();