|
1 | 1 | # Jenkins Lockable Resources Plugin |
2 | 2 |
|
3 | | -This plugins allows to define "lockable resources" in the global configuration. |
4 | | -These resources can then be "required" by jobs. If a job requires a resource |
5 | | -which is already locked, it will be put in queue until the resource is released. |
| 3 | +[](https://plugins.jenkins.io/lockable-resources) |
| 4 | +[](https://github.com/jenkinsci/lockable-resources-plugin/releases/latest) |
| 5 | +[](https://plugins.jenkins.io/lockable-resources) |
| 6 | +[](https://ci.jenkins.io/job/Plugins/job/lockable-resources-plugin/job/master/) |
| 7 | +[](https://github.com/jenkinsci/lockable-resources-plugin/blob/master/LICENSE.txt) |
| 8 | +[](https://github.com/jenkinsci/lockable-resources-plugin) |
| 9 | + |
| 10 | +This plugin allows defining lockable resources (such as printers, phones, |
| 11 | +computers, etc.) that can be used by builds. If a build requires a resource |
| 12 | +which is already locked, it will wait for the resource to be free. |
| 13 | + |
| 14 | +## Usage |
| 15 | + |
| 16 | +### Adding lockable resources |
| 17 | + |
| 18 | +1. In *Manage Jenkins* > *Configure System* go to **Lockable Resources |
| 19 | + Manager** |
| 20 | +2. Select *Add Lockable Resource* |
| 21 | + |
| 22 | +Each lockable resource has the following properties: |
| 23 | + |
| 24 | +- **Name** - A name (not containing spaces!) for this particular resource, i.e. |
| 25 | + `DK_Printer_ColorA3_2342` |
| 26 | +- **Description** - A verbose description of this particular resource, |
| 27 | + i.e. ` Printers in the Danish Office` |
| 28 | +- **Labels** - Space-delimited list of Labels (Not containing spaces) used to |
| 29 | + identify a pool of resources. i.e. `DK_Printers_Office`, |
| 30 | + `DK_Printer_Production`, `DK_Printer_Engineering` |
| 31 | +- **Reserved by** - If non-empty, the resource will be unavailable for jobs. |
| 32 | + i.e. `All printers are currently not available due to maintenance.` |
| 33 | + |
| 34 | +### Using a resource in a freestyle job |
| 35 | + |
| 36 | +When configuring the job, select **This build requires lockable resources**. |
| 37 | +Please see the help item for each field for details. |
| 38 | + |
| 39 | +### Using a resource in a pipeline job |
| 40 | + |
| 41 | +When the `lock` step is used in a Pipeline, if the resource to be locked isn't |
| 42 | +already defined in the Jenkins global configuration, an ephemeral resource is |
| 43 | +used: These resources only exist as long as any running build is referencing |
| 44 | +them. |
| 45 | + |
| 46 | +Examples: |
| 47 | + |
| 48 | +```groovy |
| 49 | +echo 'Starting' |
| 50 | +lock('my-resource-name') { |
| 51 | + echo 'Do something here that requires unique access to the resource' |
| 52 | + // any other build will wait until the one locking the resource leaves this block |
| 53 | +} |
| 54 | +echo 'Finish' |
| 55 | +``` |
| 56 | + |
| 57 | +```groovy |
| 58 | +lock(resource: 'staging-server', inversePrecedence: true) { |
| 59 | + node { |
| 60 | + servers.deploy 'staging' |
| 61 | + } |
| 62 | + input message: "Does ${jettyUrl}staging/ look good?" |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +```groovy |
| 67 | +lock(label: 'some_resource', variable: 'LOCKED_RESOURCE') { |
| 68 | + echo env.LOCKED_RESOURCE |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Detailed documentation can be found as part of the |
| 73 | +[Pipeline Steps](https://jenkins.io/doc/pipeline/steps/lockable-resources/) |
| 74 | +documentation. |
| 75 | + |
| 76 | +## Configuration as Code |
| 77 | + |
| 78 | +This plugin can be configured via |
| 79 | +[Configuration-as-Code](https://github.com/jenkinsci/configuration-as-code-plugin). |
| 80 | + |
| 81 | +### Example configuration |
| 82 | + |
| 83 | +``` |
| 84 | +unclassified: |
| 85 | + lockableResourcesManager: |
| 86 | + declaredResources: |
| 87 | + - name: "Resource_A" |
| 88 | + description: "Description_A" |
| 89 | + labels: "Label_A" |
| 90 | + reservedBy: "Reserved_A" |
| 91 | +``` |
| 92 | + |
| 93 | +## Changelog |
| 94 | + |
| 95 | +* See [GitHub Releases](https://github.com/jenkinsci/lockable-resources-plugin/releases) |
| 96 | + for recent versions. |
| 97 | +* See the [old changelog](CHANGELOG.old.md) for versions 2.5 and older. |
| 98 | + |
| 99 | +## Contributing |
| 100 | + |
| 101 | +If you want to contribute to this plugin, you probably will need a Jenkins plugin development |
| 102 | +environment. This basically means a current version of Java (Java 8 should probably be okay for now) |
| 103 | +and [Apache Maven]. See the [Jenkins Plugin Tutorial] for details. |
| 104 | + |
| 105 | +If you have the proper environment, typing: |
| 106 | + |
| 107 | + $ mvn verify |
| 108 | + |
| 109 | +should create a plugin as `target/*.hpi`, which you can install in your Jenkins instance. Running |
| 110 | + |
| 111 | + $ mvn hpi:run -Djenkins.version=2.164.1 |
| 112 | + |
| 113 | +allows you to spin up a test Jenkins instance on [localhost] to test your |
| 114 | +local changes before committing. |
| 115 | + |
| 116 | +[Apache Maven]: https://maven.apache.org/ |
| 117 | +[Jenkins Plugin Tutorial]: https://jenkins.io/doc/developer/tutorial/prepare/ |
| 118 | +[localhost]: http://localhost:8080/jenkins/ |
| 119 | + |
| 120 | +### Code Style |
| 121 | + |
| 122 | +This plugin tries to migrate to [Google Java Code Style], please try to adhere to that style |
| 123 | +whenever adding new files or making big changes to existing files. If your IDE doesn't support |
| 124 | +this style, you can use the [fmt-maven-plugin], like this: |
| 125 | + |
| 126 | + $ mvn fmt:format -DfilesNamePattern=ChangedFile\.java |
| 127 | + |
| 128 | +to reformat Java code in the proper style. |
| 129 | + |
| 130 | +[Google Java Code Style]: https://google.github.io/styleguide/javaguide.html |
| 131 | +[fmt-maven-plugin]: https://github.com/coveo/fmt-maven-plugin |
| 132 | + |
| 133 | +## License |
| 134 | + |
| 135 | +The MIT License (MIT) |
| 136 | + |
| 137 | +- Copyright 2013-2015 6WIND |
| 138 | +- Copyright 2016-2018 Antonio Muñiz |
| 139 | +- Copyright 2019 TobiX |
| 140 | + |
| 141 | +See [LICENSE](LICENSE.txt) |
0 commit comments