Merge branch 'master' into feature/340-resource-event-listener

Author: mPokornyETM

.github/workflows/auto-label-pr.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Auto-label based on title and branch
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const pr = context.payload.pull_request;

.github/workflows/dependabot-auto-merge.yml

@@ -17,4 +17,4 @@ jobs:
         run: gh pr merge --auto --squash "$PR_URL"
         env:
           PR_URL: ${{ github.event.pull_request.html_url }}
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}

README.md

@@ -84,6 +84,19 @@ echo 'Finish'
 
 ```
 
+#### Lock with a reason
+
+You can specify a reason why the resource is being locked. This is displayed
+in the lockable resources UI while the resource is locked:
+
+```groovy
+lock(resource: 'staging-server', reason: 'Running integration tests') {
+    echo 'Deploying to staging'
+}
+```
+
+The reason helps other users understand why a resource is unavailable.
+
 Example for declarative pipeline:
 
 ```groovy

src/main/java/org/jenkins/plugins/lockableresources/LockStep.java

@@ -42,6 +42,11 @@ public class LockStep extends Step implements Serializable {
     @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
     public String label = null;
 
+    /** The reason why this resource is being locked, displayed in the UI while locked. */
+    @CheckForNull
+    @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
+    public String reason = null;
+
     @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
     public int quantity = 0;
 
@@ -117,6 +122,13 @@ public void setLabel(String label) {
         }
     }
 
+    @DataBoundSetter
+    public void setReason(String reason) {
+        if (reason != null && !reason.trim().isEmpty()) {
+            this.reason = reason.trim();
+        }
+    }
+
     @DataBoundSetter
     public void setVariable(String variable) {
         if (variable != null && !variable.trim().isEmpty()) {
@@ -230,7 +242,7 @@ public String toString() {
                     .map(res -> "{" + res.toString() + "}")
                     .collect(Collectors.joining(","));
         } else if (resource != null || label != null) {
-            String ret = LockStepResource.toString(resource, label, quantity);
+            String ret = LockStepResource.toString(resource, label, quantity, reason);
             if (this.priority != 0) {
                 ret += ", Priority: " + this.priority;
             }
@@ -251,7 +263,7 @@ public void validate(boolean allowEmptyOrNullValues) {
     public List<LockStepResource> getResources() {
         List<LockStepResource> resources = new ArrayList<>();
         if (resource != null || label != null) {
-            resources.add(new LockStepResource(resource, label, quantity));
+            resources.add(new LockStepResource(resource, label, quantity, reason));
         }
 
         if (extra != null) {

src/main/java/org/jenkins/plugins/lockableresources/LockStepExecution.java

@@ -90,7 +90,7 @@ public boolean start() throws Exception {
                     return false;
                 }
 
-                if (!lrm.lock(available, run)) {
+                if (!lrm.lock(available, run, step.reason)) {
                     // this here is very defensive code, and you will probably never hit it. (hopefully)
                     LOGGER.warning("Internal program error: Can not lock resources: " + available);
                     onLockFailed(logger, resourceHolderList);
@@ -156,7 +156,8 @@ private void onLockFailed(PrintStream logger, List<LockableResourcesStruct> reso
                     step.toString(),
                     step.variable,
                     step.inversePrecedence,
-                    step.priority);
+                    step.priority,
+                    step.reason);
         }
     }
 

src/main/java/org/jenkins/plugins/lockableresources/LockStepResource.java

@@ -35,10 +35,20 @@ public class LockStepResource extends AbstractDescribableImpl<LockStepResource>
     @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
     public int quantity = 0;
 
+    /** The reason why this resource is being locked, displayed in the UI while locked. */
+    @CheckForNull
+    @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
+    public String reason = null;
+
     LockStepResource(@Nullable String resource, @Nullable String label, int quantity) {
+        this(resource, label, quantity, null);
+    }
+
+    LockStepResource(@Nullable String resource, @Nullable String label, int quantity, @Nullable String reason) {
         this.resource = Util.fixEmptyAndTrim(resource);
         this.label = Util.fixEmptyAndTrim(label);
         this.quantity = quantity;
+        this.reason = Util.fixEmptyAndTrim(reason);
     }
 
     @DataBoundConstructor
@@ -56,24 +66,37 @@ public void setQuantity(int quantity) {
         this.quantity = quantity;
     }
 
+    @DataBoundSetter
+    public void setReason(String reason) {
+        this.reason = Util.fixEmptyAndTrim(reason);
+    }
+
     @Override
     public String toString() {
-        return toString(resource, label, quantity);
+        return toString(resource, label, quantity, reason);
     }
 
     public static String toString(String resource, String label, int quantity) {
+        return toString(resource, label, quantity, null);
+    }
+
+    public static String toString(String resource, String label, int quantity, String reason) {
         // a label takes always priority
+        StringBuilder sb = new StringBuilder();
         if (label != null) {
+            sb.append("Label: ").append(label);
             if (quantity > 0) {
-                return "Label: " + label + ", Quantity: " + quantity;
+                sb.append(", Quantity: ").append(quantity);
             }
-            return "Label: " + label;
+        } else if (resource != null) {
+            sb.append("Resource: ").append(resource);
+        } else {
+            return "[no resource/label specified - probably a bug]";
         }
-        // make sure there is an actual resource specified
-        if (resource != null) {
-            return "Resource: " + resource;
+        if (reason != null && !reason.isEmpty()) {
+            sb.append(", Reason: ").append(reason);
         }
-        return "[no resource/label specified - probably a bug]";
+        return sb.toString();
     }
 
     // -------------------------------------------------------------------------

src/main/java/org/jenkins/plugins/lockableresources/LockableResource.java

@@ -72,6 +72,12 @@ public class LockableResource extends AbstractDescribableImpl<LockableResource>
     private Date reservedTimestamp = null;
     private String note = "";
 
+    /**
+     * The reason why this resource is currently locked. Set via the lock() step's reason parameter.
+     * Cleared when the resource is unlocked.
+     */
+    private String lockReason = "";
+
     /**
      * Track that a currently reserved resource was originally reserved for someone else, or locked
      * for some other job, and explicitly taken away - e.g. for SUT post-mortem while a test job runs.
@@ -255,6 +261,26 @@ public void setNote(@Nullable String note) {
         this.note = Util.fixNull(note);
     }
 
+    /**
+     * Returns the reason why this resource is currently locked.
+     *
+     * @return The lock reason, or empty string if not set.
+     */
+    @Exported
+    public String getLockReason() {
+        return this.lockReason;
+    }
+
+    /**
+     * Sets the reason why this resource is being locked. This is typically set via the lock() step's
+     * reason parameter and cleared when the resource is unlocked.
+     *
+     * @param lockReason The reason for locking, or null to clear.
+     */
+    public void setLockReason(@Nullable String lockReason) {
+        this.lockReason = Util.fixNull(lockReason);
+    }
+
     @DataBoundSetter
     public void setEphemeral(boolean ephemeral) {
         this.ephemeral = ephemeral;
@@ -422,6 +448,7 @@ private boolean evaluateScript(@NonNull SecureGroovyScript script, @CheckForNull
         binding.setVariable("resourceDescription", description);
         binding.setVariable("resourceLabels", this.getLabelsAsList());
         binding.setVariable("resourceNote", note);
+        binding.setVariable("resourceLockReason", lockReason);
         try {
             Object result = script.evaluate(Jenkins.get().getPluginManager().uberClassLoader, binding, null);
             if (LOGGER.isLoggable(Level.FINE)) {
@@ -650,20 +677,27 @@ public boolean isStolen() {
     }
 
     public void reserve(String userName) {
+        reserve(userName, null);
+    }
+
+    public void reserve(String userName, String reason) {
         setReservedBy(userName);
         setReservedTimestamp(new Date());
+        setLockReason(reason);
     }
 
     public void unReserve() {
         this.setReservedBy(null);
         this.setReservedTimestamp(null);
+        this.setLockReason(null);
         this.stolen = false;
     }
 
     public void reset() {
         this.unReserve();
         this.unqueue();
         this.setBuild(null);
+        this.setLockReason(null);
         invalidateCaches();
     }
 
@@ -678,6 +712,7 @@ public void copyUnconfigurableProperties(final LockableResource sourceResource)
             setReservedTimestamp(sourceResource.getReservedTimestamp());
             setNote(sourceResource.getNote());
             setReservedBy(sourceResource.getReservedBy());
+            setLockReason(sourceResource.getLockReason());
         }
     }
 
@@ -689,6 +724,7 @@ public void resetUnconfigurableProperties() {
         setReservedBy(null);
         setReservedTimestamp(null);
         setNote("");
+        setLockReason("");
     }
 
     /**