[JENKINS-76027] Allow Bitbucket build status to be customised

Define extension point to allow customisation of build status. Additional data could be sei in the optionalData field where all entries will be serialised starting from the root object.

Author: nfalco79

.gitignore

@@ -18,4 +18,6 @@ work/
 
 # VSCode
 .factorypath
-META-INF/
+META-INF/
+/.apt_generated/
+/.apt_generated_tests/

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/BitbucketNotifier.java

@@ -23,6 +23,7 @@
  */
 package com.cloudbees.jenkins.plugins.bitbucket.api;
 
+import com.cloudbees.jenkins.plugins.bitbucket.api.buildstatus.BitbucketBuildStatusNotifier;
 import com.cloudbees.jenkins.plugins.bitbucket.api.webhook.BitbucketWebhookConfiguration;
 import com.cloudbees.jenkins.plugins.bitbucket.client.repository.UserRoleInRepository;
 import com.cloudbees.jenkins.plugins.bitbucket.filesystem.BitbucketSCMFile;
@@ -297,8 +298,10 @@ List<? extends BitbucketRepository> getRepositories(@CheckForNull UserRoleInRepo
      * Set the build status for the given commit hash.
      *
      * @param status the status object to be serialized
+     * @deprecated Use the appropriate {@link BitbucketBuildStatusNotifier} instead of this
      * @throws IOException if there was a network communications error.
      */
+    @Deprecated(since = "937.0.0", forRemoval = true)
     void postBuildStatus(@NonNull BitbucketBuildStatus status) throws IOException;
 
     /**

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

@@ -0,0 +1,102 @@
+/*
+ * 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;
+
+import edu.umd.cs.findbugs.annotations.CheckForNull;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import java.io.IOException;
+
+/**
+ * The implementation provides an authenticated client for a configured
+ * Bitbucket endpoint.
+ *
+ * @apiNote This interface is intended to be consumed in an extension point.
+ *
+ * @author Nikolas Falco
+ * @since 937.0.0
+ */
+public interface BitbucketAuthenticatedClient extends AutoCloseable {
+
+    /**
+     * The owner of the repository where register the webhook.
+     */
+    @NonNull
+    String getRepositoryOwner();
+
+    /**
+     * Name of the repository where register the webhook.
+     */
+    @CheckForNull
+    String getRepositoryName();
+
+    /**
+     * Perform an HTTP POST to the configured endpoint.
+     * <p>
+     * Request will be sent as JSON
+     *
+     * @param path to call, it will prepend with the server URL
+     * @param payload to send
+     * @return the JSON string of the response
+     * @throws IOException in case of connection failures
+     */
+    String post(@NonNull String path, @CheckForNull String payload) throws IOException;
+
+    /**
+     * Perform an HTTP PUT to the configured endpoint.
+     * <p>
+     * Request will be sent as JSON
+     *
+     * @param path to call, it will prepend with the server URL
+     * @param payload to send
+     * @return the JSON string of the response
+     * @throws IOException in case of connection failures
+     */
+    String put(@NonNull String path, @CheckForNull String payload) throws IOException;
+
+    /**
+     * Perform an HTTP DELETE to the configured endpoint.
+     * <p>
+     * Request will be sent as JSON
+     *
+     * @param path to call, it will prepend with the server URL
+     * @return the JSON string of the response
+     * @throws IOException in case of connection failures
+     */
+    String delete(@NonNull String path) throws IOException;
+
+    /**
+     * Perform an HTTP GET to the configured endpoint.
+     * <p>
+     * Request will be sent as JSON
+     *
+     * @param path to call, it will prepend with the server URL
+     * @return the JSON string of the response
+     * @throws IOException in case of connection failures
+     */
+    @NonNull
+    String get(@NonNull String path) throws IOException;
+
+    @Override
+    void close() throws IOException;
+}

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

@@ -23,14 +23,20 @@
  */
 package com.cloudbees.jenkins.plugins.bitbucket.api;
 
+import com.cloudbees.jenkins.plugins.bitbucket.api.buildstatus.BitbucketBuildStatusCustomizer;
+import com.fasterxml.jackson.annotation.JsonAnyGetter;
 import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonValue;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
 import org.kohsuke.accmod.Restricted;
 import org.kohsuke.accmod.restrictions.DoNotUse;
 
 public class BitbucketBuildStatus {
-
     /**
      * Enumeration of possible Bitbucket commit notification states
      */
@@ -43,20 +49,18 @@ public enum Status {
         CANCELLED("CANCELLED"),
         SUCCESSFUL("SUCCESSFUL");
 
-        private final String status;
-
-        Status(final String status) {
-            this.status = status;
-        }
+        @JsonValue
+        private final String label;
 
-        @Override
-        public String toString() {
-            return status;
+        Status(final String label) {
+            this.label = label;
         }
     }
 
     /**
-     * The commit hash to set the status on
+     * The commit hash to set the status on.
+     * <p>
+     * This is not part of the payload.
      */
     @JsonIgnore
     private String hash;
@@ -107,9 +111,16 @@ public String toString() {
      */
     private int buildNumber;
 
+    /**
+     * A set of new informations.
+     */
+    private Map<String, Object> optionalData;
+
     // Used for marshalling/unmarshalling
     @Restricted(DoNotUse.class)
-    public BitbucketBuildStatus() {}
+    public BitbucketBuildStatus() {
+        this.optionalData = new HashMap<>();
+    }
 
     public BitbucketBuildStatus(String hash,
                                 String description,
@@ -141,7 +152,9 @@ public BitbucketBuildStatus(@NonNull BitbucketBuildStatus other) {
         this.name = other.name;
         this.refname = other.refname;
         this.buildDuration = other.buildDuration;
+        this.buildNumber = other.buildNumber;
         this.parent = other.parent;
+        this.optionalData = other.optionalData != null ? new HashMap<>(other.optionalData) : new HashMap<>();
     }
 
     public String getHash() {
@@ -160,8 +173,8 @@ public void setDescription(String description) {
         this.description = description;
     }
 
-    public String getState() {
-        return state.toString();
+    public Status getState() {
+        return state;
     }
 
     public void setState(Status state) {
@@ -223,4 +236,83 @@ public void setParent(String parent) {
     public String getParent() {
         return parent;
     }
+
+    /**
+     * This represent additional informations contributed by
+     * {@link BitbucketBuildStatusCustomizer}s.
+     * <p>
+     * The contents of this map will be added to the root of the sent payload.
+     * <p>
+     * For example:
+     *
+     * <pre>
+     * buildStatus.addOptionalData("testResults", new TestResult(1, 2, 3));
+     * buildStatus.addOptionalData("optX", true);
+     * </pre>
+     *
+     * Will be serialised as:
+     *
+     * <pre>
+     * {
+     *     "description": "The build is in progress..."
+     *     ...
+     *     "testResult": {
+     *         "successful": 5,
+     *         "failed": 2,
+     *         "skipped": 1
+     *     },
+     *     "optX": true
+     * }
+     * </pre>
+     *
+     * @return an unmodifiable map of extra informations
+     */
+    @JsonAnyGetter
+    public Map<String, Object> getOptionalData() {
+        return Collections.unmodifiableMap(optionalData);
+    }
+
+    /**
+     * Add a new attribute to the payload to send. If the attribute has already
+     * been valued than it is ignored.
+     *
+     * @param attribute attribute of build status, refer to the Bitbucket API
+     * @param value bean to associate to the given attribute name
+     * @see <a href="https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commit-statuses/#api-repositories-workspace-repo-slug-commit-commit-statuses-build-post">Cloud REST API</a>
+     * @see <a href="https://developer.atlassian.com/server/bitbucket/rest/v906/api-group-builds-and-deployments/#api-api-latest-projects-projectkey-repos-repositoryslug-commits-commitid-builds-post">Data Center REST API</a>
+     */
+    public void addOptionalData(String attribute, Object value) {
+        this.optionalData.putIfAbsent(attribute, value);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(buildDuration, buildNumber, description, hash, key, name, parent, refname, state, url, optionalData);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if (obj == null) {
+            return false;
+        }
+        if (getClass() != obj.getClass()) {
+            return false;
+        }
+        BitbucketBuildStatus other = (BitbucketBuildStatus) obj;
+        return buildDuration == other.buildDuration
+                && buildNumber == other.buildNumber
+                && Objects.equals(description, other.description)
+                && Objects.equals(hash, other.hash)
+                && Objects.equals(key, other.key)
+                && Objects.equals(name, other.name)
+                && Objects.equals(parent, other.parent)
+                && Objects.equals(refname, other.refname)
+                && state == other.state
+                && Objects.equals(url, other.url)
+                && Objects.equals(optionalData, other.optionalData);
+    }
+
 }