Quick usage guide

• Install the plugin
• In Manage Jenkins > Configure System go to Lockable Resources Manager   
  • Select Add Lockable Resource    
    
    

    Brief description of the named fields:

    • Name - A name (not containing spaces!) for this particular resource, i.e. DK_Printers.
    • Description - A verbose description of this particular resource, i.e.Printers in the Danish Office
    • Labels - Space-delimited list of Labels (Not containing spaces) used to identify a pool of resources. i.e. DK_Printers_Office   DK_Printer_Production   DK_Printer_Engineering
    • Reserved by - If anything is written here, the resource will be taken and therefore unavailable for other jobs. i.e. All printers are currently not available due to maintenance.

• In Jenkins > <job name> >  Configure > General
  
  

  Brief description of the named fields:

  • Resources - The name or names of resources needed. In this example, DK_Printers will select all of the three printers in the pool.
  • Label - One or more Labels to select resources. In this example, DK_Printer_Production   DK_Printer_Engineering will select two labeled printers in the larger pool.
  
  

• Start a build.
  • Under build #<number> select  Locked Resources 
  • You should see something like: This build has locked the following resources: <resource_name> - <resource description>

• Start a different build which uses the same resource. * You will see *Build Queue in Jenkins status/menu showing job name
  • Hover text shows Started <by>, Waiting for resources <resources list>, Waiting for <time>

Pipeline usage

• When the lock step is used in a Pipeline, if the resource to be locked isn't already defined in the Jenkins global configuration, it'll be set up automatically.
• The arguments to the lock step are:
  • resource - The resource name to lock as defined in Global settings. If inversePrecedence isn't also specified, the step can be called as lock('some-resource') without the named argument.
  • label - can be used to require locks on multiple resources concurrently. The build will wait until all resources tagged with the given label are available. Only this or resource can be used simultaneously.
  • quantity - (optional) specifies the number of resources required within the selected label. If not set, all resources from the label will be required.
  • inversePrecedence - (optional) By default waiting builds are given the lock in the same order they requested to acquire it. If inversePrecedence is set to true, this will be done in reverse order instead, so that the newest build to request the lock will be granted it first.
  • variable - (optional) When locking a resource via a label you can use variable to set an environment variable with the name of the locked resource.

• Examples:

  echo 'Starting'
  lock('my-resource-name') {
    echo 'Do something here that requires unique access to the resource'
    // any other build will wait until the one locking the resource leaves this block
  }
  echo 'Finish'
  

  lock(resource: 'staging-server', inversePrecedence: true) {
      node {
          servers.deploy 'staging'
      }
      input message: "Does ${jettyUrl}staging/ look good?"
  }
  

  lock(label: 'test-farm') {
      parallel test1: {
          node('farm-server-linux') {
              sh './run-tests.sh'
          }
      },
      test2: {
          node('farm-server-windows') {
              sh './run-tests.bat'
          }
      }
  }
  

  lock(label: 'some_resource', variable: 'LOCKED_RESOURCE') {
    echo env.LOCKED_RESOURCE
  }

Changelog

Release 2.5 (2019-3-25)

• Fix security issue

Release 2.4 (2019-1-18)

• JENKINS-46555 - Fix NPE on invalid entries.

Release 2.3 (2018-6-26)

• JENKINS-34433 - Signal queued Pipeline tasks on unreserve

• Allow locking multiple resources in Pipeline

Release 2.2 (2018-3-6)

• JENKINS-40997 - New configuration option to get the name of the locked resource inside the lock block (Pipeline).

• JENKINS-49734 - Add a PauseAction to the build when waiting for locking, so Pipeline representations in the UI are correctly shown.
• JENKINS-43574 - Fixed the "empty" resources lock (message: "acquired lock on []")

Release 2.1 (2017-11-13)

• JENKINS-47235 - Trim whitespace from resource names.
• JENKINS-47754 - Fix broken Freestyle behavior.
  
  

Release 1.11.2 (2017-3-15)

• JENKINS-40368 - Locked resources are not always freed up on Pipeline hard kill when there are other pipelines waiting on the Resource

Release 1.11.1 (2017-2-20)

• JENKINS-40879 - Locked areas are executed multiple times in parallel

Release 1.11 (2016-12-19)

• JENKINS-34268 - lock multiple resources concurrently
• JENKINS-34273 - add the number of resources to lock from a given label

Release 1.10 (2016-07-12)

• JENKINS-36479 - properly clean up resources locked by hard-killed or deleted while in progress Pipeline builds.

Release 1.9 (2016-06-01)

• Reserved resources parameter visibility in environment (related to SECURITY-170)

Release 1.8 (2016-04-14)

• Pipeline compatibility: lock step

Release 1.2 (2014-02-05)

• Manual reservation/un-reservation of resources now require specific permissions

Release 1.1 (2014-02-03)

• Allow jobs to require a subset of specified resources (the number of required resources is configurable)
• Allow manual reservation/un-reservation of resources

Release 1.0 (2013-12-12)

• Initial release