[JENKINS-47213] Opening a PR when the branch is still building with "Exclude branches that are also filed as PRs" leads to a never ending build in BitBucket

Bitbucket enhance its build status API with a refname (Cloud) and ref (Server) property to indicate the owner's git reference. This can be used as a sort of filter in case multiple build statuses have been associated with the same commit.
For example, this means that when browsing commits from the webpage, you will see all the build statuses associated with a commit (no scope); but, you should only see one when you land on the pull request webpage (scoped).

NOTE: At the time of implementation once a build status is created, it cannot be deleted via the API. If refname is set, it cannot be set to null. The property appears to participate in some way in the primary key of the build status, multiple build statuses with the same key but different refnames are allowed, especially in the use case the update APIs return an HTTP 500 error.
Available documentations:
* https://developer.atlassian.com/server/bitbucket/rest/v903/api-group-builds-and-deployments/#api-api-latest-projects-projectkey-repos-repositoryslug-commits-commitid-builds-post
* https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commit-statuses/#api-repositories-workspace-repo-slug-commit-commit-statuses-build-post
does not explain precisly how this property should be valued. This force me to set the property to null in case of pull request, otherwise, the build status disappear from the webpage and branch restriction and merge conditions will not work.

Author: nfalco79

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

@@ -29,6 +29,7 @@
 import com.cloudbees.jenkins.plugins.bitbucket.client.BitbucketCloudApiClient;
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.Nullable;
 import hudson.Extension;
 import hudson.FilePath;
 import hudson.model.Result;
@@ -44,6 +45,7 @@
 import java.net.URL;
 import jenkins.model.JenkinsLocationConfiguration;
 import jenkins.plugins.git.AbstractGitSCMSource;
+import jenkins.scm.api.SCMHead;
 import jenkins.scm.api.SCMHeadObserver;
 import jenkins.scm.api.SCMRevision;
 import jenkins.scm.api.SCMRevisionAction;
@@ -96,9 +98,12 @@ static String checkURL(@NonNull String url, BitbucketApi bitbucket) {
         }
     }
 
-    private static void createStatus(@NonNull Run<?, ?> build, @NonNull TaskListener listener,
-        @NonNull BitbucketApi bitbucket, @NonNull String key, @NonNull String hash)
-            throws IOException, InterruptedException {
+    private static void createStatus(@NonNull Run<?, ?> build,
+                                     @NonNull TaskListener listener,
+                                     @NonNull BitbucketApi bitbucket,
+                                     @NonNull String key,
+                                     @NonNull String hash,
+                                     @Nullable String refName) throws IOException, InterruptedException {
 
         final SCMSource source = SCMSource.SourceByItem.findSource(build.getParent());
         if (!(source instanceof BitbucketSCMSource)) {
@@ -161,7 +166,11 @@ private static void createStatus(@NonNull Run<?, ?> build, @NonNull TaskListener
 
         if (state != null) {
             BitbucketChangesetCommentNotifier notifier = new BitbucketChangesetCommentNotifier(bitbucket);
-            notifier.buildStatus(new BitbucketBuildStatus(hash, statusDescription, state, url, key, name));
+            BitbucketBuildStatus buildStatus = new BitbucketBuildStatus(hash, statusDescription, state, url, key, name, refName);
+            buildStatus.setBuildDuration(build.getDuration());
+            buildStatus.setBuildNumber(build.getNumber());
+            // TODO testResults should be provided by an extension point that integrates JUnit or anything else plugin
+            notifier.buildStatus(buildStatus);
             if (result != null) {
                 listener.getLogger().println("[Bitbucket] Build result notified");
             }
@@ -196,18 +205,32 @@ private static void sendNotifications(BitbucketSCMSource source, Run<?, ?> build
             .anyMatch(ExcludeOriginPRBranchesSCMHeadFilter.class::isInstance);
 
         String key;
+        String refName;
         BitbucketApi bitbucket;
         if (rev instanceof PullRequestSCMRevision) {
             listener.getLogger().println("[Bitbucket] Notifying pull request build result");
             PullRequestSCMHead head = (PullRequestSCMHead) rev.getHead();
             key = getBuildKey(build, head.getOriginName(), shareBuildKeyBetweenBranchAndPR);
+            /*
+             * in case of pull request it's not clear at all how to value refname. The
+             * bitbucket documentation does not help and using values like
+             * - refs/heads/PR-748;
+             * - refs/pull-requests/748,
+             * - refs/pull-requests/feature/test;
+             * causes the build status disappear from the UI page.
+             * The only working value is null. If commit is used for two different
+             * pull requests than you will get double status in both PRs
+             */
+            refName = null; // "refs/pull-requests/" + head.getBranchName();
             bitbucket = source.buildBitbucketClient(head);
         } else {
             listener.getLogger().println("[Bitbucket] Notifying commit build result");
-            key = getBuildKey(build, rev.getHead().getName(), shareBuildKeyBetweenBranchAndPR);
+            SCMHead head = rev.getHead();
+            key = getBuildKey(build, head.getName(), shareBuildKeyBetweenBranchAndPR);
+            refName = "refs/heads/" + head.getName();
             bitbucket = source.buildBitbucketClient();
         }
-        createStatus(build, listener, bitbucket, key, hash);
+        createStatus(build, listener, bitbucket, key, hash, refName);
     }
 
     @CheckForNull

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

@@ -25,6 +25,7 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.Nullable;
 import org.apache.commons.codec.digest.DigestUtils;
 import org.kohsuke.accmod.Restricted;
 import org.kohsuke.accmod.restrictions.DoNotUse;
@@ -87,17 +88,39 @@ public String toString() {
      */
     private String name;
 
+    /**
+     * The fully qualified git reference e.g. refs/heads/master.
+     */
+    private String refname;
+
+    /**
+     * Duration of a completed build in milliseconds.
+     */
+    private long buildDuration;
+
+    /**
+     * A unique identifier of this particular run.
+     */
+    private int buildNumber;
+
     // Used for marshalling/unmarshalling
     @Restricted(DoNotUse.class)
     public BitbucketBuildStatus() {}
 
-    public BitbucketBuildStatus(String hash, String description, Status state, String url, String key, String name) {
+    public BitbucketBuildStatus(String hash,
+                                String description,
+                                @NonNull Status state,
+                                String url,
+                                @NonNull String key,
+                                String name,
+                                @Nullable String refname) {
         this.hash = hash;
         this.description = description;
         this.state = state;
         this.url = url;
         this.key = DigestUtils.md5Hex(key);
         this.name = name;
+        this.refname = refname;
     }
 
     /**
@@ -112,6 +135,8 @@ public BitbucketBuildStatus(@NonNull BitbucketBuildStatus other) {
         this.url = other.url;
         this.key = other.key;
         this.name = other.name;
+        this.refname = other.refname;
+        this.buildDuration = other.buildDuration;
     }
 
     public String getHash() {
@@ -162,4 +187,28 @@ public void setName(String name) {
         this.name = name;
     }
 
+    public String getRefname() {
+        return refname;
+    }
+
+    public void setRefname(String refname) {
+        this.refname = refname;
+    }
+
+    public long getBuildDuration() {
+        return buildDuration;
+    }
+
+    public void setBuildDuration(long buildDuration) {
+        this.buildDuration = buildDuration;
+    }
+
+    public int getBuildNumber() {
+        return buildNumber;
+    }
+
+    public void setBuildNumber(int buildNumber) {
+        this.buildNumber = buildNumber;
+    }
+
 }

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/server/client/BitbucketServerAPIClient.java

@@ -47,6 +47,7 @@
 import com.cloudbees.jenkins.plugins.bitbucket.server.BitbucketServerWebhookImplementation;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.branch.BitbucketServerBranch;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.branch.BitbucketServerBranches;
+import com.cloudbees.jenkins.plugins.bitbucket.server.client.branch.BitbucketServerBuildStatus;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.branch.BitbucketServerCommit;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.mirror.BitbucketMirrorServerDescriptors;
 import com.cloudbees.jenkins.plugins.bitbucket.server.client.mirror.BitbucketMirroredRepositoryDescriptors;
@@ -144,7 +145,7 @@ public class BitbucketServerAPIClient extends AbstractBitbucketApi implements Bi
     private static final String WEBHOOK_REPOSITORY_PATH = WEBHOOK_BASE_PATH + "/projects/{owner}/repos/{repo}/configurations";
     private static final String WEBHOOK_REPOSITORY_CONFIG_PATH = WEBHOOK_REPOSITORY_PATH + "/{id}";
 
-    private static final String API_COMMIT_STATUS_PATH = "/rest/build-status/1.0/commits{/hash}";
+    private static final String API_COMMIT_STATUS_PATH = API_BASE_PATH + "/projects/{owner}/repos/{repo}/commits/{hash}/builds";
 
     private static final String API_MIRRORS_FOR_REPO_PATH = "/rest/mirroring/1.0/repos/{id}/mirrors";
     private static final String API_MIRRORS_PATH = "/rest/mirroring/1.0/mirrorServers";
@@ -509,10 +510,12 @@ public void postCommitComment(@NonNull String hash, @NonNull String comment) thr
      */
     @Override
     public void postBuildStatus(@NonNull BitbucketBuildStatus status) throws IOException, InterruptedException {
-        BitbucketBuildStatus newStatus = new BitbucketBuildStatus(status);
+        BitbucketServerBuildStatus newStatus = new BitbucketServerBuildStatus(status);
         newStatus.setName(truncateMiddle(newStatus.getName(), 255));
 
         String url = UriTemplate.fromTemplate(API_COMMIT_STATUS_PATH)
+                .set("owner", getUserCentricOwner())
+                .set("repo", repositoryName)
                 .set("hash", newStatus.getHash())
                 .expand();
         postRequest(url, JsonParser.toJson(newStatus));

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/server/client/branch/BitbucketServerBuildStatus.java

@@ -0,0 +1,28 @@
+package com.cloudbees.jenkins.plugins.bitbucket.server.client.branch;
+
+import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketBuildStatus;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class BitbucketServerBuildStatus extends BitbucketBuildStatus {
+
+    /**
+     * Copy constructor.
+     *
+     * @param other from copy to.
+     */
+    public BitbucketServerBuildStatus(BitbucketBuildStatus other) {
+        super(other);
+    }
+
+    @JsonProperty("ref")
+    @Override
+    public String getRefname() {
+        return super.getRefname();
+    }
+
+    @JsonProperty("duration")
+    @Override
+    public long getBuildDuration() {
+        return super.getBuildDuration();
+    }
+}

src/test/resources/com/cloudbees/jenkins/plugins/bitbucket/server/payload/1.0-projects-amuniz-repos-test-repos-commits-046d9a3c1532acf4cf08fe93235c00e4d673c1d3-builds.json

@@ -0,0 +1,48 @@
+{
+  "key": "da005fd0512173736e591039b282053a",
+  "type": "build",
+  "state": "FAILED",
+  "name": "test » BUILD test (#748) #1",
+  "refname": null,
+  "commit": {
+    "hash": "046d9a3c1532acf4cf08fe93235c00e4d673c1d3",
+    "links": {
+      "self": {
+        "href": "https://api.bitbucket.org/2.0/repositories/amuniz/test-repos/commit/046d9a3c1532acf4cf08fe93235c00e4d673c1d3"
+      },
+      "html": {
+        "href": "https://bitbucket.org/amuniz/test-repos/commits/046d9a3c1532acf4cf08fe93235c00e4d673c1d3"
+      }
+    },
+    "type": "commit"
+  },
+  "url": "https://localhost/job/test/job/PR-748/1/display/redirect",
+  "repository": {
+    "type": "repository",
+    "full_name": "amuniz/test-repos",
+    "links": {
+      "self": {
+        "href": "https://api.bitbucket.org/2.0/repositories/amuniz/test-repos"
+      },
+      "html": {
+        "href": "https://bitbucket.org/amuniz/test-repos"
+      },
+      "avatar": {
+        "href": "https://bytebucket.org/ravatar/%7Bf991126e-6825-40ea-a1c2-e72c336ae41e%7D?ts=java"
+      }
+    },
+    "name": "test-repos",
+    "uuid": "{f991126e-6825-40ea-a1c2-e72c336ae41e}"
+  },
+  "description": "There was a failure building this commit.",
+  "created_on": "2024-11-30T19:04:49.002285+00:00",
+  "updated_on": "2024-12-01T14:58:03.086428+00:00",
+  "links": {
+    "self": {
+      "href": "https://api.bitbucket.org/2.0/repositories/amuniz/test-repos/commit/046d9a3c1532acf4cf08fe93235c00e4d673c1d3/statuses/build/da005fd0512173736e591039b282053a"
+    },
+    "commit": {
+      "href": "https://api.bitbucket.org/2.0/repositories/amuniz/test-repos/commit/046d9a3c1532acf4cf08fe93235c00e4d673c1d3"
+    }
+  }
+}