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

Add webhook extensible interface to provide custom implementation of wehbook from configuration to the APIs to register it on Bitbucket

Author: nfalco79

docs/USER_GUIDE.adoc

@@ -192,7 +192,7 @@ If you want be able to perform git push operation from CLI than you have to setu
 
 image::images/screenshot-17.png[]
 
-=== App Passwords - DEPRECATED (Bitbucket Cloud only)
+=== App Passwords (Bitbucket Cloud only)
 
 Bitbucket https://community.atlassian.com/t5/Bitbucket-articles/Announcement-Bitbucket-Cloud-account-password-usage-for-Git-over/ba-p/1948231[deprecated usage of Atlassian account password] for Bitbucket API and Git over HTTPS starting from March 1st, 2022.
 
@@ -203,21 +203,6 @@ First, create a new _app password_ in Bitbucket as instructed in the https://sup
 Then create a new _Username with password credentials_ in Jenkins, enter the Bitbucket username (not the email) in the _Username_ field and the created app password in the _Password_ field.
 
  IMPORTANT: App passwords do not support email address as a username for authentication. Using the email address will raise an authentication error in scanning/checkout process.
- The app passoword authentication has been deprecated by Atlassian and starting from September 9th, 2025 will not longer available for creation. https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation[Read here] for more informations.
-
-=== User API Token (Bitbucket Cloud only)
-
-Bitbucket https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation[deprecated usage of Atlassian App Password] for Bitbucket API and Git over HTTPS starting from September 9th, 2025.
-
-The plugin can make use of an user API token with scopes instead of the app password.
-
-First, create a new _User API token_ in Bitbucket as instructed in the https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/[Bitbucket API Token Documentation]. At least allow _read_ access for project, repositories and pull requests. Also, you may need to allow _read_ and _write_ access for webhooks depending on your pipeline's triggers.
-
-image::images/screenshot-22.png[]
-
-Then create a new _Username with password credentials_ in Jenkins, enter the Atlassian Account email (not the username) in the _Username_ field and the created API token in the _Password_ field.
-
- IMPORTANT: API token requires the email address as a username to authenticate using the BitbucketAPIs. Using the username will raise an authentication error in scanning/checkout process. API token without scope does not work.
 
 === OAuth credentials (Bitbucket Cloud only)
 

docs/images/screenshot-22.png

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.cloudbees.jenkins.plugins.bitbucket.api.webhook;
+package com.cloudbees.jenkins.plugins.bitbucket.api.hook;
 
 import com.cloudbees.jenkins.plugins.bitbucket.BitbucketSCMSource;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
@@ -47,7 +47,7 @@
  * the incoming request as much as possible or the hook will be rejected.
  */
 @Restricted(Beta.class)
-public interface BitbucketWebhookProcessor extends ExtensionPoint {
+public interface BitbucketHookProcessor extends ExtensionPoint {
     static final String SCAN_ON_EMPTY_CHANGES_PROPERTY_NAME = "bitbucket.hooks.processor.scanOnEmptyChanges";
 
     /**
@@ -104,11 +104,11 @@ default Map<String, Object> buildHookContext(@NonNull HttpServletRequest request
      * @param payload request
      * @param endpoint configured for the given
      *        {@link #getServerURL(Map, MultiValuedMap)}
-     * @throws BitbucketWebhookProcessorException when signature verification fails
+     * @throws BitbucketHookProcessorException when signature verification fails
      */
     void verifyPayload(@NonNull Map<String, String> headers,
                        @NonNull String payload,
-                       @NonNull BitbucketEndpoint endpoint) throws BitbucketWebhookProcessorException;
+                       @NonNull BitbucketEndpoint endpoint) throws BitbucketHookProcessorException;
 
     /**
      * Settings that will trigger a re-index of the multibranch

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookProcessor.java renamed to src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/hook/BitbucketHookProcessor.java

@@ -21,15 +21,15 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.cloudbees.jenkins.plugins.bitbucket.api.webhook;
+package com.cloudbees.jenkins.plugins.bitbucket.api.hook;
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketException;
 
-public class BitbucketWebhookProcessorException extends BitbucketException {
+public class BitbucketHookProcessorException extends BitbucketException {
     private static final long serialVersionUID = 6682700868741672883L;
     private final int httpCode;
 
-    public BitbucketWebhookProcessorException(int httpCode, String message) {
+    public BitbucketHookProcessorException(int httpCode, String message) {
         super(message);
         this.httpCode = httpCode;
     }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhookProcessorException.java renamed to src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/hook/BitbucketHookProcessorException.java

@@ -47,7 +47,6 @@
 import com.cloudbees.jenkins.plugins.bitbucket.impl.client.ICheckedCallable;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.credentials.BitbucketAccessTokenAuthenticator;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.credentials.BitbucketOAuthAuthenticator;
-import com.cloudbees.jenkins.plugins.bitbucket.impl.credentials.BitbucketUserAPITokenAuthenticator;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.credentials.BitbucketUsernamePasswordAuthenticator;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.BitbucketApiUtils;
 import com.cloudbees.jenkins.plugins.bitbucket.impl.util.JsonParser;
@@ -148,7 +147,6 @@ protected boolean isSupportedAuthenticator(@CheckForNull BitbucketAuthenticator
         return authenticator == null
                 || authenticator instanceof BitbucketAccessTokenAuthenticator
                 || authenticator instanceof BitbucketOAuthAuthenticator
-                || authenticator instanceof BitbucketUserAPITokenAuthenticator // API access token
                 || authenticator instanceof BitbucketUsernamePasswordAuthenticator; // app password
     }
 

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/webhook/BitbucketWebhook.java

@@ -25,8 +25,8 @@
 
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpoint;
 import com.cloudbees.jenkins.plugins.bitbucket.api.endpoint.BitbucketEndpointProvider;
-import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookProcessor;
-import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookProcessorException;
+import com.cloudbees.jenkins.plugins.bitbucket.api.hook.BitbucketHookProcessor;
+import com.cloudbees.jenkins.plugins.bitbucket.api.hook.BitbucketHookProcessorException;
 import hudson.Extension;
 import hudson.ExtensionList;
 import hudson.model.UnprotectedRootAction;
@@ -93,7 +93,7 @@ public HttpResponse doNotify(StaplerRequest2 req) throws IOException {
         try {
             Map<String, String> reqHeaders = getHeaders(req);
             MultiValuedMap<String, String> reqParameters = getParameters(req);
-            BitbucketWebhookProcessor hookProcessor = getHookProcessor(reqHeaders, reqParameters);
+            BitbucketHookProcessor hookProcessor = getHookProcessor(reqHeaders, reqParameters);
 
             String body = IOUtils.toString(req.getInputStream(), StandardCharsets.UTF_8);
             if (StringUtils.isEmpty(body)) {
@@ -120,37 +120,37 @@ public HttpResponse doNotify(StaplerRequest2 req) throws IOException {
             String eventType = hookProcessor.getEventType(Collections.unmodifiableMap(reqHeaders), MultiMapUtils.unmodifiableMultiValuedMap(reqParameters));
 
             hookProcessor.process(eventType, body, context, endpoint);
-        } catch(BitbucketWebhookProcessorException e) {
+        } catch(BitbucketHookProcessorException e) {
             return HttpResponses.error(e.getHttpCode(), e.getMessage());
         }
         return HttpResponses.ok();
     }
 
-    private BitbucketWebhookProcessor getHookProcessor(Map<String, String> reqHeaders,
+    private BitbucketHookProcessor getHookProcessor(Map<String, String> reqHeaders,
                                                     MultiValuedMap<String, String> reqParameters) {
-        BitbucketWebhookProcessor hookProcessor;
+        BitbucketHookProcessor hookProcessor;
 
-        List<BitbucketWebhookProcessor> matchingProcessors = getHookProcessors()
+        List<BitbucketHookProcessor> matchingProcessors = getHookProcessors()
             .filter(processor -> processor.canHandle(Collections.unmodifiableMap(reqHeaders), MultiMapUtils.unmodifiableMultiValuedMap(reqParameters)))
             .toList();
         if (matchingProcessors.isEmpty()) {
             logger.warning(() -> "No processor found for the incoming Bitbucket hook. Skipping.");
-            throw new BitbucketWebhookProcessorException(HttpServletResponse.SC_BAD_REQUEST, "No processor found that supports this event. Refer to the user documentation on how configure the webHook in Bitbucket at https://github.com/jenkinsci/bitbucket-branch-source-plugin/blob/master/docs/USER_GUIDE.adoc#webhooks-registering");
+            throw new BitbucketHookProcessorException(HttpServletResponse.SC_BAD_REQUEST, "No processor found that supports this event. Refer to the user documentation on how configure the webHook in Bitbucket at https://github.com/jenkinsci/bitbucket-branch-source-plugin/blob/master/docs/USER_GUIDE.adoc#webhooks-registering");
         } else if (matchingProcessors.size() > 1) {
             String processors = StringUtils.joinWith("\n- ", matchingProcessors.stream()
                 .map(p -> p.getClass().getName())
                 .toList());
             logger.severe(() -> "More processors found that handle the incoming Bitbucket hook:\n" + processors);
-            throw new BitbucketWebhookProcessorException(HttpServletResponse.SC_CONFLICT, "More processors found that handle the incoming Bitbucket hook.");
+            throw new BitbucketHookProcessorException(HttpServletResponse.SC_CONFLICT, "More processors found that handle the incoming Bitbucket hook.");
         } else {
             hookProcessor = matchingProcessors.get(0);
             logger.fine(() -> "Hook processor " + hookProcessor.getClass().getName() + " found.");
         }
         return hookProcessor;
     }
 
-    /*test*/ Stream<BitbucketWebhookProcessor> getHookProcessors() {
-        return ExtensionList.lookup(BitbucketWebhookProcessor.class).stream();
+    /*test*/ Stream<BitbucketHookProcessor> getHookProcessors() {
+        return ExtensionList.lookup(BitbucketHookProcessor.class).stream();
     }
 
     private MultiValuedMap<String, String> getParameters(StaplerRequest2 req) {