Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Groovy Label Assignment on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Provides "Groovy script to restrict where this project can be run" in job configuration pages.

What's this?

This plugin provides "Groovy script to restrict where this project can be run" to the job configuration page:

  • The value returned from the script is treated as a label expression.
    • This label expression overrides "Restrict where this project can be run", and "Slaves"/"Label-expression" axes of multi-configuration projects.
    • A non-string values is converted into a string with toString().
    • Returning null or empty string does not override existing label expressions.
  • Following variables are binded to the Groovy script:
    • Parameters defined with "This build is parameterized".
    • Axes defined with a multi-configuration project.
    • Environment variables defined with plugins.
  • A build does not start (trigger is ignored) in following cases:
    • No groovy script is configured even though Groovy Label Assignment is enabled in the job.
    • The groovy script contains syntax errors.
    • The groovy script throws an exception at the runtime.

Use cases

Use case 1

Think a following scenario:

  • You have to build a project for multiple platforms: arm, win, linux
  • There are following nodes:





















You can manage this by using multi-configuration project as followings:

  • Define a User-defined axis "platform": arm, win, linux
  • Define a Slaves axis "slave": armcc, vs2010, gcc
  • Define "Combination Filter" as following:

    (platform == "arm" && slave=="armcc") || (platform == "win" && slave=="vs2010") || (platform == "linux" && slave=="gcc")

Groovy Label Assignment plugin provides following alternate solution:

  • Define a User-defined axis "platform": arm, win, linux
  • Define "Groovy script to restrict where this project can be run":

    def labelMap = [
        arm: "armcc",
        win: "vs2010",
        linux: "gcc",
    return labelMap.get(binding.getVariables().get("platform"));

Use case 2

Consider to create a job with which developers build a source tree.

  • You want developers can build both a release build and a snapshot with that job. Developers select release or snapshot when they trigger a build.
  • Release build must be built on nodes labeled "RELEASE" for releasing. Snapshot build must be built not on those nodes, but on other nodes.

You can create a satisfying job by using Groovy Label Assignment plugin:

  • Parameterize the job.
  • Define a Boolen Value parameter "release", which specifies the triggering build is for release.
  • Define "Groovy script to restrict where this project can be run":

    return (release == "true")?"RELEASE":"!RELEASE"


  • Some variables may not be properly binded:
    • Some type of parameters may be not properly binded.
    • Environment variables of some type of plugins may be not properly binded.
    • This is for Groovy Label Assignment plugin works when a build is going to be created, and is not created. Parameters and plugins that refers build information does not work properly.
  • When Groovy Label Assignment plugin fails, a build is rejected silently. Failures happen in following cases. You can refer the system log to see why Groovy Label Assignment plugin failed.
    • Groovy script is not defined.
    • Groovy script contains syntax errors.
    • Groovy script failed at the runtime.
      • Especially in case referring non-binded variables. It often happens when running with multi-configuration project. In that case, you can access the variable safely as following:

    • Returned value cannot be parsed as a label expression.




To report a bug or request an enhancement to this plugin please create a ticket in JIRA (you need to login or to sign up for an account). Also have a look on How to report an issue

T P Key Summary

How does this work?

This plugin works as following:

  1. When a new build is triggerd, GroovyLabelAssignmentQueueDecisionHandler is called.
  2. If GroovyLabelAssignmentProperty is assigned to the job, call it.
  3. EnvironmentContributingAction#buildEnvVars() is called for retrieving variables to bind to the Groovy script.
    • Parameters are defined here.
  4. Retrieve axes values configured to that job and bind to the Groovy script.
  5. Run Groovy script.
  6. Parse returned value as a label expression.
  7. Assign it with LabelAssignmentAction.

Change Log

Version 1.2.0 (May 8, 2016)

  • Now targets Jenkins 1.509 and later (was 1.466).
  • Groovy scripts run with Script Security Plugin (JENKINS-27535)
    • Existing scripts are configured to run in the Groovy sandboxes.
    • You may have to approve some methods to allow run in the sandbox, or approve your scripts to allow run out of the sandbox.
    • See Script Security Plugin for details.

Version 1.1.1 (Sep 13, 2015)

  • Fixed: fails to find nodes with a specified label when the label is once removed from all nodes (JENKINS-30135)

Version 1.1.0 (Mar 21, 2015)

  • Expose current Jenkins job to the Groovy script as "currentJob" variable (JENKINS-27424)

Version 1.0.0 (Jun 05, 2013)

  • Initial release.


  1. Unknown User (samapico)

    Is there any way to use some set of labels for the matrix flyweight executor, and another set of labels for the matrix configuration executors?

    Without this plugin, I had the following behavior:

    • Parent job runs on <label restriction>
    • Child jobs runs wherever they want

    With this plugin, I can easily make the child jobs run where I want with something like:

    return "MyLabel"

    But this also makes the parent job run on "MyLabel". I would want my parent jobs to always run on the master, for example. I tried doing something with the "MatrixConfiguration" variable, but I can't figure it out and I don't know Groovy much.

    1. Unknown User (samapico)

      Ah, finally got it... I wasn't using the name of my axis correctly. Here it goes:

      if (binding.getVariables().get("<name of an axis>"))
          return "<label restriction for child executor>";
      return "<label restriction for parent executor>";

      No idea if this is the most elegant way, but it seems to work fine.

  2. Unknown User (gangadhar)

    Is this pluggin available via job DSL ? I am trying to configure jobs via DSL and cannot find a command in the DSL reference. 

    1. Unknown User (annetheagile)

      I am so happy to find this plugin! being forced to use hard coded node names/labels has been problematic. This way I can add a subset clause and remove it later instead of having to keep reverting/etc. Also I plan to use it with a parameter , so the user can choose the machine/cluster desired.

      1.it looks like we now have an option to try an autogenerated solution.


      The generated DSL will not work for all plugins, e.g. if a plugin does not use the @DataBoundConstructor and @DataBoundSetter annotations to declare parameters. In that case The Configure Block can be used to generate the config XML.

      2.elsewhere for another plugin a user noted how to add a simple plugin.