This plugin allows defining lockable resources (such as printers, phones, computers, etc.) that can be used by builds. If a build requires a resource which is already locked, it will wait for the resource to be free.

1. In Manage Jenkins > Configure System go to Lockable Resources Manager
2. Select Add Lockable Resource

Each lockable resource has the following properties:

• Name - A name (not containing spaces!) for this particular resource, i.e. DK_Printer_ColorA3_2342
• 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 non-empty, the resource will be unavailable for jobs. i.e. All printers are currently not available due to maintenance.

When configuring the job, select This build requires lockable resources. Please see the help item for each field for details.

When the lock step is used in a Pipeline, if the resource to be locked isn't already defined in the Jenkins global configuration, an ephemeral resource is used: These resources only exist as long as any running build is referencing them.

Examples:

Acquire lock

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'

Take first position in queue

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

Resolve a variable configured with the resource name

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

When multiple locks are acquired, each will be assigned to a numbered variable:

lock(label: 'some_resource', variable: 'LOCKED_RESOURCE', quantity: 2) {
  // comma separated names of all acquired locks
  echo env.LOCKED_RESOURCE

  // first lock
  echo env.LOCKED_RESOURCE0

  // second lock
  echo env.LOCKED_RESOURCE1
}

Skip executing the block if there is a queue

lock(resource: 'some_resource', skipIfLocked: true) {
  echo 'Do something now or never!'
}

Detailed documentation can be found as part of the Pipeline Steps documentation.

This plugin can be configured via Configuration-as-Code.

unclassified:
  lockableResourcesManager:
    declaredResources:
      - name: "Resource_A"
        description: "Description_A"
        labels: "Label_A"
        reservedBy: "Reserved_A"

• See GitHub Releases for recent versions.
• See the old changelog for versions 2.5 and older.

If you want to contribute to this plugin, you probably will need a Jenkins plugin development environment. This basically means a current version of Java (Java 8 should probably be okay for now) and Apache Maven. See the Jenkins Plugin Tutorial for details.

If you have the proper environment, typing:

$ mvn verify

should create a plugin as target/*.hpi, which you can install in your Jenkins instance. Running

$ mvn hpi:run -Djenkins.version=2.249.1

allows you to spin up a test Jenkins instance on localhost to test your local changes before committing.

This plugin tries to migrate to Google Java Code Style, please try to adhere to that style whenever adding new files or making big changes to existing files. If your IDE doesn't support this style, you can use the fmt-maven-plugin, like this:

$ mvn fmt:format -DfilesNamePattern=ChangedFile\.java

to reformat Java code in the proper style.

The MIT License (MIT)

• Copyright 2013-2015 6WIND
• Copyright 2016-2018 Antonio Muñiz
• Copyright 2019 TobiX
• Copyright 2017-2022 Jim Klimov

See LICENSE