Merge branch 'test/773-timeout-queue-cleanup' of https://github.com/jenkinsci/lockable-resources-plugin into test/773-timeout-queue-cleanup

Author: mPokornyETM

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

@@ -1,8 +1,12 @@
 # Auto-enable squash merge for Dependabot PRs
 # GitHub will automatically merge once all required checks pass
+#
+# Uses pull_request_target so the workflow runs in the base-branch context
+# and the default GITHUB_TOKEN has write permissions (Dependabot-triggered
+# pull_request events only expose a read-only token).
 name: Dependabot Auto-merge
 
-on: pull_request
+on: pull_request_target
 
 permissions:
   contents: write
@@ -17,4 +21,4 @@ jobs:
         run: gh pr merge --auto --squash "$PR_URL"
         env:
           PR_URL: ${{ github.event.pull_request.html_url }}
-          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+          GH_TOKEN: ${{ github.token }}

pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>org.jenkins-ci.plugins</groupId>
     <artifactId>plugin</artifactId>
-    <version>5.2102.v5f5fe09fccf1</version>
+    <version>6.2152.ve00a_731c3ce9</version>
     <relativePath />
   </parent>
 
@@ -71,7 +71,7 @@
       <dependency>
         <groupId>io.jenkins.tools.bom</groupId>
         <artifactId>bom-${jenkins.baseline}.x</artifactId>
-        <version>6269.v7a_159d68a_366</version>
+        <version>6329.v403d8c87a_5ce</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>

src/doc/examples/lock-with-timeout.md

@@ -0,0 +1,77 @@
+## Lock with allocation timeout
+
+By default, the `lock` step waits indefinitely until the requested resource becomes available.
+With `timeoutForAllocateResource` you can set a maximum wait time — if the resource is not
+acquired within that period, the build fails immediately instead of blocking the queue forever.
+
+This is useful when:
+- You prefer a fast failure over an indefinitely blocked pipeline
+- You want to detect resource starvation early
+- Your CI/CD has SLAs that cap how long a job may wait
+
+### Pipeline (scripted)
+
+```groovy
+node {
+    // Wait up to 5 minutes for the resource, then fail
+    lock(resource: 'my-printer', timeoutForAllocateResource: 5, timeoutUnit: 'MINUTES') {
+        echo "Printer locked, printing ..."
+    }
+}
+```
+
+### Pipeline (declarative)
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Deploy') {
+            options {
+                lock(resource: 'staging-env', timeoutForAllocateResource: 10, timeoutUnit: 'MINUTES')
+            }
+            steps {
+                echo "Deploying to staging ..."
+            }
+        }
+    }
+}
+```
+
+### Label-based locking with timeout
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Test') {
+            steps {
+                lock(label: 'phone', quantity: 1, variable: 'PHONE',
+                     timeoutForAllocateResource: 2, timeoutUnit: 'MINUTES') {
+                    echo "Running tests on ${env.PHONE}"
+                }
+            }
+        }
+    }
+}
+```
+
+### Freestyle jobs
+
+In a freestyle job configuration, go to **This build requires lockable resources** and set:
+- **Lock wait timeout**: the maximum time to wait (e.g. `5`)
+- **Timeout unit**: `SECONDS`, `MINUTES`, or `HOURS`
+
+If the resource is not available within the configured timeout, the build is automatically
+removed from the Jenkins queue.
+
+### Timeout values
+
+| `timeoutUnit` | Description |
+|---------------|-------------|
+| `SECONDS`     | Timeout in seconds |
+| `MINUTES`     | Timeout in minutes (default) |
+| `HOURS`       | Timeout in hours |
+
+Setting `timeoutForAllocateResource: 0` (the default) disables the timeout — the build
+waits indefinitely, which preserves the original behaviour.

src/doc/examples/readme.md

@@ -13,3 +13,4 @@ If you have a question, please open a [GitHub issue](https://github.com/jenkinsc
 - [Scripted vs declarative pipeline](scripted-vs-declarative-pipeline.md)
 - [Timeout inside lock](timeout-inside-lock.md)
 - [Dynamic resource pool expansion](dynamic-resource-pool-expansion.md)
+- [Lock with allocation timeout](lock-with-timeout.md)

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

@@ -71,6 +71,20 @@ public class LockStep extends Step implements Serializable {
     @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
     public int priority = 0;
 
+    /**
+     * Timeout in the specified {@link #timeoutUnit} for waiting to acquire the resource.
+     * 0 means no timeout (wait indefinitely). When the timeout expires, the step fails
+     * with an exception instead of waiting forever.
+     */
+    @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
+    public long timeoutForAllocateResource = 0;
+
+    /**
+     * Time unit for {@link #timeoutForAllocateResource}. Defaults to MINUTES.
+     */
+    @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
+    public String timeoutUnit = "MINUTES";
+
     // it should be LockStep() - without params. But keeping this for backward compatibility
     // so `lock('resource1')` still works and `lock(label: 'label1', quantity: 3)` works too (resource
     // is not required)
@@ -154,6 +168,24 @@ public void setExtra(@CheckForNull List<LockStepResource> extra) {
         this.extra = extra;
     }
 
+    @DataBoundSetter
+    public void setTimeoutForAllocateResource(long timeoutForAllocateResource) {
+        this.timeoutForAllocateResource = Math.max(0, timeoutForAllocateResource);
+    }
+
+    @DataBoundSetter
+    public void setTimeoutUnit(String timeoutUnit) {
+        if (timeoutUnit != null && !timeoutUnit.trim().isEmpty()) {
+            // Validate it is a valid TimeUnit name
+            try {
+                java.util.concurrent.TimeUnit.valueOf(timeoutUnit.toUpperCase(Locale.ENGLISH));
+            } catch (IllegalArgumentException e) {
+                throw new IllegalArgumentException("Invalid timeoutUnit: " + timeoutUnit);
+            }
+            this.timeoutUnit = timeoutUnit.toUpperCase(Locale.ENGLISH);
+        }
+    }
+
     @Extension
     public static final class DescriptorImpl extends StepDescriptor {
 
@@ -229,6 +261,20 @@ public static FormValidation doCheckResourceSelectStrategy(
             return FormValidation.ok();
         }
 
+        @RequirePOST
+        public ListBoxModel doFillTimeoutUnitItems(@AncestorInPath Item item) {
+            if (item != null) {
+                item.checkPermission(Item.CONFIGURE);
+            } else {
+                Jenkins.get().checkPermission(Jenkins.ADMINISTER);
+            }
+            ListBoxModel items = new ListBoxModel();
+            items.add("Seconds", "SECONDS");
+            items.add("Minutes", "MINUTES");
+            items.add("Hours", "HOURS");
+            return items;
+        }
+
         @Override
         public Set<Class<?>> getRequiredContext() {
             return Collections.singleton(TaskListener.class);

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

@@ -147,8 +147,12 @@ private void onLockFailed(PrintStream logger, List<LockableResourcesStruct> reso
             getContext().onSuccess(null);
         } else {
             this.printBlockCause(logger, resourceHolderList);
-            LockableResourcesManager.printLogs(
-                    "[" + step + "] is not free, waiting for execution ...", Level.FINE, LOGGER, logger);
+            String waitMsg = "[" + step + "] is not free, waiting for execution ...";
+            if (step.timeoutForAllocateResource > 0) {
+                waitMsg += " (timeout: " + step.timeoutForAllocateResource + " "
+                        + step.timeoutUnit.toLowerCase(java.util.Locale.ENGLISH) + ")";
+            }
+            LockableResourcesManager.printLogs(waitMsg, Level.FINE, LOGGER, logger);
             LockableResourcesManager lrm = LockableResourcesManager.get();
             lrm.queueContext(
                     getContext(),
@@ -157,7 +161,9 @@ private void onLockFailed(PrintStream logger, List<LockableResourcesStruct> reso
                     step.variable,
                     step.inversePrecedence,
                     step.priority,
-                    step.reason);
+                    step.reason,
+                    step.timeoutForAllocateResource,
+                    step.timeoutUnit);
         }
     }
 
@@ -205,8 +211,8 @@ public static void proceed(
                     context.newBodyInvoker().withCallback(new Callback(resourceNames, resourceDescription));
             if (variable != null && !variable.isEmpty()) {
                 // set the variable for the duration of the block
-                bodyInvoker.withContext(
-                        EnvironmentExpander.merge(context.get(EnvironmentExpander.class), new EnvironmentExpander() {
+                bodyInvoker.withContext(EnvironmentExpander.merge(
+                        context.get(EnvironmentExpander.class), new EnvironmentExpander() {
                             private static final long serialVersionUID = -3431466225193397896L;
 
                             @Override