[JENKINS-76027] Allow Bitbucket build status to be customised (#1101)

Define extension point to allow customisation of build status.
Additional data could be set in the optionalData field where all entries will be added to 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);
+    }
+
 }