[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,7 @@ 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));
+            notifier.buildStatus(new BitbucketBuildStatus(hash, statusDescription, state, url, key, name, refName));
             if (result != null) {
                 listener.getLogger().println("[Bitbucket] Build result notified");
             }
@@ -195,18 +200,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,29 @@ public String toString() {
      */
     private String name;
 
+    /**
+     * The fully qualified git reference e.g. refs/heads/master.
+     */
+    private String refname;
+
     // 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 +125,7 @@ public BitbucketBuildStatus(@NonNull BitbucketBuildStatus other) {
         this.url = other.url;
         this.key = other.key;
         this.name = other.name;
+        this.refname = other.refname;
     }
 
     public String getHash() {
@@ -162,4 +176,12 @@ public void setName(String name) {
         this.name = name;
     }
 
+    public String getRefname() {
+        return refname;
+    }
+
+    public void setRefname(String refname) {
+        this.refname = refname;
+    }
+
 }

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;
@@ -509,7 +510,7 @@ 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)

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

@@ -0,0 +1,22 @@
+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();
+    }
+}