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 Conditional BuildStep on the plugin site for more information.

A buildstep wrapping any number of other buildsteps, controlling their execution based on a defined condition.


This plugin requires the TokenMacro Plugin and the Run Condition Plugin to be installed!

  • Ever wanted to have more control whether a step should be executed or not?
  • Want to reduce the number of jobs doing nearly the same thing?

Add a conditional buildstep which acts as a container. It will allow you to define a condition controling the execution of the step(s).


There are multiple conditions one can choose of, these are all defined by the Run Condition Plugin

Missing builder

If you're not able to add the builder of your choice within a conditional build step (because it's not available within the dropdown), then this is likely because the builder does not provide a @DataBoundConstructor constructor and/or the Descriptor does not extend hudson.tasks.BuildStepDescriptor. For non programmers: the plugin you would like to use does not yet follow the newest Jenkins coding guidelines. Without this, the conditional buildstep plugin is not able to work with it.

Conditional step (single)

This build step allows you to select any build step and define a condition to control whether the step should be executed.
For reasons why you might want to use this step, see Why use Conditional step (single)?

Conditional steps (multiple)

A 'Conditional steps (multiple)' container is able to contain any number of any other buildsteps (e.g. Shell, Ant, Maven,...) and you can have any number of 'Conditional Steps' containers, each configured with a different condition.


please check out the examples at the Run Condition Plugin

Known issues

Open Issues  (${entries.size()} issues)

T Key Summary

Version History

1.3.6 (9. June 2017)

  • integrate JENKINS-43887 upgrade parent pom to 2.x (thanks varyvol #14)
  • ConditionalBuilder now implements DependencyDeclarer (thanks TWestling #12)

1.3.5 (16. June 2016)

  • fix JENKINS-35526, update to DependencyDeclarer (PR#10 thanks fbelzunc)
  • fix JENKINS-34971 describe advanced options about failing the evaluation of a condition

1.3.3 (13. Nov. 2013)

  • fix JENKINS-20543 fix "NoSuchMethodError: org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuildStepHelper.getContainedBuilders()"

1.3.2 (10. Nov.2013)

  • add helper (ConditionalBuildStepHelper) to support working with wrapped build steps to support JENKINS-18967
  • enhance ConditionalBuildStepHelper to also return pre- and post builders from a maven project

1.3 (16. July 2013)

1.2.2 (2. June 2013)

  • fix JENKINS-17836 exception if there is no builder defined within the conditional build step

1.2.1 (1. Nov 2012)

  • Fix JENKINS-13871 Using "Conditional build step" and "Parameterized build step" in same step is preventing parallel executions of same job

1.2 (11. Okt 2012)

  • Fix JENKINS-14118 show builds triggered through "Conditional buildstep" plugin reported as downstream builds for the current build.

1.1 (6. May 2012)

  • Fix JENKINS-13618 Unable to use multiple Conditional Steps in the Prebuild section of Multi configuration job

1.0 (31. March 2012)

0.0.3 (31. Dec. 2011)

  • Fix JENKINS-12036 - conditional buildsteps does not support matrix build

0.0.2 (14. Nov. 2011)


  • initial

Help and Support

For Help and support please use the Jenkins Users mailing list or the Issue tracker (JIRA).


  1. Unknown User (allinonething)

    Is it possible to use variable values comparison as condition? I tried "${PARAM}==Value1" but got following output: 

    [${PART}==Part1] evaluated to [${PART}==Part1]

    When I'm using just "${PART}" as condition it is being resolved correctly to it's value:

    [${PART}] evaluated to [Part1] (invert: false) execute --> false
  2. Unknown User (giulianobr)

    I have the same issue of Sergey D, any update about this?

  3. Unknown User (livermouse)

    Same thing as Sergey and Giullano. Looks like


    is not evaluating properly here

    Here's the output from my logs when my condition is ${ENVIRONMENT}==staging:

    Oct 29, 2011 5:30:22 AM org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuilder
    FINE: failed to resolve condition via TokenMacro: Unrecognized macro 'ENVIRONMENT' in '${ENVIRONMENT}==staging'

    If I change the condition to ${ENVIRONMENT} then I get this:

    Oct 29, 2011 5:32:17 AM org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuilder
    FINE: resolve ${ENVIRONMENT} to staging
    Oct 29, 2011 5:32:17 AM org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuilder
    FINE: failed to resolve condition via TokenMacro: Unrecognized macro 'ENVIRONMENT' in '${ENVIRONMENT}'

    I'm using the Parameterized Build Plugin to set a Choice Parameter called ENVIRONMENT.

  4. Unknown User (domi)

    please open an issue in jira, comments are not monitored...

  5. Unknown User (jacojm)

    I discovered a way to use it despite the problem:

    In my case I want to trigger the job only if a concrete variable (i.e.: "VARIABLE") has been defined so checking "invert" option and using this condition works fine for me:


    Explanation: what it really is expecting is just a "true" / other value, so if VARIABLE has no value it will leave a simple "true" in the field.

  6. Unknown User (msunkara)

    In my jenkins I have "Execute Python Script" as build step but this step is not available as builder in "Conditional Step" or "Conditional Steps".

    Is there a way I can make "Execute Python Script" available as builder?

    I really appreciate your help. Thank you, MS

  7. Unknown User (titoftit)


    It's don't work with Hudson 2.2.0 ?? 

    1. Unknown User (kopfwunde)


      Jenkins has become become the first choice in the community (well deserved as I think) and plugins for Hudson/Jenkins can be compatible against each other but this is not guaranteed.

      I think that will get less and less likely as the two server will fork more over time. That'll then become a responsibility of the maintainers to make the plugins compatible.

      Hudson is dead, hail to the king, baby! :)

  8. Hi,

    I have a problem with this plugin.

    I've set the configuration for my job to mark build as unstable if the run condition fails, but it doesn't work. If the condition fails the buildstep under the condition is not runned and the build result is success. Instead, it should mark the build as unstable. Same with "mark build as fail" option.

    It is a bug or I just didn't configure something as it should?

  9. Unknown User (xiaopan3322)

    What a great Plugin!!!

  10. Unknown User (thoudayer)

    I have an issue when I try to add a "ArtifactoryDeployer" build step (or a native "Archive artifacts" build step) in a "Conditional Step (multiple)". When I save the modification, I have a java exception, see below.
    There is no issue when I add this "ArtifactoryDeployer" (or the native "Archive artifacts" build step) build step in a "Conditional Step (single)" ! Any Idea ?

     javax.servlet.ServletException: java.lang.RuntimeException: Failed to instantiate class org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuilder from {"":["15","0"],"runCondition":{"stapler-class":"org.jenkins_ci.plugins.run_condition.logic.And","conditions":[{"":"2","condition":{"stapler-class":"org.jenkins_ci.plugins.run_condition.core.BooleanCondition","token":"${ENV, var=\"GAME_MARKET_amazon\"}"}},{"":"2","condition":{"stapler-class":"org.jenkins_ci.plugins.run_condition.core.BooleanCondition","token":"${ENV, var=\"GAME_ENVIR_prod\"}"}}]},"runner":{"stapler-class":"org.jenkins_ci.plugins.run_condition.BuildStepRunner$Fail"},"conditionalbuilders":[{"command":"echo Hello","stapler-class":"hudson.tasks.BatchFile","kind":"hudson.tasks.BatchFile"},{"msBuildName":"MSBuild .Net 4.0","msBuildFile":"${WORKSPACE}/Test/Build/Test.sln","cmdLineArgs":"/p:Platform=Android /verbosity:detailed /p:Configuration=${CONFIGURATION}","buildVariablesAsProperties":false,"continueOnBuildFailure":false,"stapler-class":"hudson.plugins.msbuild.MsBuildBuilder","kind":"hudson.plugins.msbuild.MsBuildBuilder"},{"deployedArtifact":{"includes":"**/*","basedir":"","remote":"${BUILD_ID}","excludes":"","flatten":false,"failNoFilesDeploy":false,"deleteRemote":false,"deleteRemoteArtifacts":false},"deployEvenBuildFail":false,"stapler-class":"org.jenkinsci.plugins.artifactdeployer.ArtifactDeployerPublisher","kind":"org.jenkinsci.plugins.artifactdeployer.ArtifactDeployerPublisher"}],"stapler-class":"org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuilder","kind":"org.jenkinsci.plugins.conditionalbuildstep.ConditionalBuilder"}
    	at org.kohsuke.stapler.Stapler.tryInvoke(Stapler.java:719)
    	at org.kohsuke.stapler.Stapler.invoke(Stapler.java:770)
    	at org.kohsuke.stapler.MetaClass$6.doDispatch(MetaClass.java:241)
    	at org.kohsuke.stapler.NameBasedDispatcher.dispatch(NameBasedDispatcher.java:53)
    	at org.kohsuke.stapler.Stapler.tryInvoke(Stapler.java:677)
    	at org.kohsuke.stapler.Stapler.invoke(Stapler.java:770)
    	at org.kohsuke.stapler.MetaClass$6.doDispatch(MetaClass.java:241)
    	at org.kohsuke.stapler.NameBasedDispatcher.dispatch(NameBasedDispatcher.java:53)
    	at org.kohsuke.stapler.Stapler.tryInvoke(Stapler.java:677)
    	at org.kohsuke.stapler.Stapler.invoke(Stapler.java:770)
    	at org.kohsuke.stapler.Stapler.invoke(Stapler.java:583)
    	at org.kohsuke.stapler.Stapler.service(Stapler.java:214)
    	at javax.servlet.http.HttpServlet.service(HttpServlet.java:45)
    	at winstone.ServletConfiguration.execute(ServletConfiguration.java:248)
    	at winstone.RequestDispatcher.forward(RequestDispatcher.java:333)
    	at winstone.RequestDispatcher.doFilter(RequestDispatcher.java:376)
    	at hudson.util.PluginServletFilter$1.doFilter(PluginServletFilter.java:95)
    	at hudson.plugins.greenballs.GreenBallFilter.doFilter(GreenBallFilter.java:58)
    	at hudson.util.PluginServletFilter$1.doFilter(PluginServletFilter.java:98)
    	at net.bull.javamelody.MonitoringFilter.doFilter(MonitoringFilter.java:206)
    	at net.bull.javamelody.MonitoringFilter.doFilter(MonitoringFilter.java:179)
    	at net.bull.javamelody.PluginMonitoringFilter.doFilter(PluginMonitoringFilter.java:86)
    	at org.jvnet.hudson.plugins.monitoring.HudsonMonitoringFilter.doFilter(HudsonMonitoringFilter.java:84)
    	at hudson.util.PluginServletFilter$1.doFilter(PluginServletFilter.java:98)
    	at hudson.plugins.audit_trail.AuditTrailFilter.doFilter(AuditTrailFilter.java:66)
    	at hudson.util.PluginServletFilter$1.doFilter(PluginServletFilter.java:98)
    	at hudson.util.PluginServletFilter.doFilter(PluginServletFilter.java:87)
    	at winstone.FilterConfiguration.execute(FilterConfiguration.java:194)
    	at winstone.RequestDispatcher.doFilter(RequestDispatcher.java:366)
    	at hudson.security.csrf.CrumbFilter.doFilter(CrumbFilter.java:48)
    	at winstone.FilterConfiguration.execute(FilterConfiguration.java:194)
    	at winstone.RequestDispatcher.doFilter(RequestDispatcher.java:366)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:84)
    	at hudson.security.UnwrapSecurityExceptionFilter.doFilter(UnwrapSecurityExceptionFilter.java:51)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at org.acegisecurity.ui.ExceptionTranslationFilter.doFilter(ExceptionTranslationFilter.java:124)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at org.acegisecurity.providers.anonymous.AnonymousProcessingFilter.doFilter(AnonymousProcessingFilter.java:125)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at org.acegisecurity.ui.rememberme.RememberMeProcessingFilter.doFilter(RememberMeProcessingFilter.java:142)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at org.acegisecurity.ui.AbstractProcessingFilter.doFilter(AbstractProcessingFilter.java:271)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at org.acegisecurity.ui.basicauth.BasicProcessingFilter.doFilter(BasicProcessingFilter.java:174)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at jenkins.security.ApiTokenFilter.doFilter(ApiTokenFilter.java:64)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at org.acegisecurity.context.HttpSessionContextIntegrationFilter.doFilter(HttpSessionContextIntegrationFilter.java:249)
    	at hudson.security.HttpSessionContextIntegrationFilter2.doFilter(HttpSessionContextIntegrationFilter2.java:66)
    	at hudson.security.ChainedServletFilter$1.doFilter(ChainedServletFilter.java:87)
    	at hudson.security.ChainedServletFilter.doFilter(ChainedServletFilter.java:76)
    	at hudson.security.HudsonFilter.doFilter(HudsonFilter.java:164)
    	at winstone.FilterConfiguration.execute(FilterConfiguration.java:194)
    	at winstone.RequestDispatcher.doFilter(RequestDispatcher.java:366)
    	at org.kohsuke.stapler.compression.CompressionFilter.doFilter(CompressionFilter.java:50)
    	at winstone.FilterConfiguration.execute(FilterConfiguration.java:194)
    	at winstone.RequestDispatcher.doFilter(RequestDispatcher.java:366)
    	at hudson.util.CharacterEncodingFilter.doFilter(CharacterEncodingFilter.java:81)
    	at winstone.FilterConfiguration.execute(FilterConfiguration.java:194)
    	at winstone.RequestDispatcher.doFilter(RequestDispatcher.java:366)
    	at winstone.RequestDispatcher.forward(RequestDispatcher.java:331)
    	at winstone.RequestHandlerThread.processRequest(RequestHandlerThread.java:227)
    	at winstone.RequestHandlerThread.run(RequestHandlerThread.java:150)
    	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:441)
    	at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:303)
    	at java.util.concurrent.FutureTask.run(FutureTask.java:138)
    	at winstone.BoundedExecutorService$1.run(BoundedExecutorService.java:77)
    	at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:886)
    	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:908)
    	at java.lang.Thread.run(Thread.java:662)
    1. Unknown User (leedega)

      I too am experiencing this problem only with the "Artifact Deployer" plugin. If anyone has any suggestions I'd appreciate it.

      My configuration is as follows:

      • Jenkins v1.509.1 (LTS edition)
      • Artifact Deployer Plug-in v0.27
      • Conditoinal Build Step Plug-in v1.2.1
  11. Unknown User (aartemov)

    There are two ways: Conditional step (multiple) and Conditional step (single). As I understand, there's no difference between them except of you can't add another step if you've chosen the second variant. But it's always no sense to use this variant - Conditional step (single), because every time there's a chance that you will need to add an additional step. And Conditional step (multiple) is handy and short enough, I don't see any problems in using it even when I need only one step.

  12. Unknown User (shyamchander01)

    Hi All

    Am new to jenkins and i have studied about the Conditional Build step plugin it is really awesome features like logical and , logical or

    however am not able to get any plugin which works as "if , else" all the conditional will be working as "if" but there is no else.

    At the same time I do not want to execute any if else in shell is there any plugin or a way to use if else.

    Step 1:

    if (condition)

    { }



    Step 2:


  13. Unknown User (odklizec)

    Hi folks,

    Does anyone have an idea what kind of condition should I create to perform a night build only if there was committed something to SCM during the day? In other words, I just want to perform a night build ONLY in case there was previously performed (during the day) a "Poll SCM changes" based build.

    At the moment, our jobs are configured to perform "DAILY" builds based of polling SMC changes and the time scheduled "NIGHTLY" builds, which are performed regardless if there was committed something in the SCM. I would like to change that.

    Is that possible with the Conditional BuildStep Plugin or should I use different plugin for this?

    Thank you in advance!

    Have a nice day,
    Pavel Kudrys

  14. Unknown User (unstoppabledrew)

    Maybe I'm missing something obvious, but I can't get this to work using build status for the failure case. A simple example: I create a standard build step, execute shell command, return 0. Subsequent conditional build steps using the 'Always' and 'build status: success/success' run as expected, and the conditional step using 'build status: failure/failure' doesn't. However, If I change the initial build step to return 1, none of the other steps are executed, Jenkins just marks the build as failed and stops.

    1. Unknown User (unstoppabledrew)

      From further experiments, it looks like this only works as post-build actions. Using any build step & flexible publish, we are able to do stuff based on the build status, just not during the actual build phase.

  15. Unknown User (taherkf)

    The examples in the run-condition page ( https://wiki.jenkins-ci.org/display/JENKINS/Run+Condition+Plugin ) shows one example for 'publish junit reports if we have some files' .

    I dont see the option at all which says 'Conditional action'  which would have Run and Action with this plugin ?  

    In my view I only see Run and then Builder : no Action option .. ? 

  16. Unknown User (davida2009)

    What condition would I use to specify that a build step should only be run if the slave is the one specified by the condition?

  17. Unknown User (robertchen117)

    condition, execute a shell like:  exit 1, and if evaluation fail mark the build fail. 

    But even exit 1, the build is still success. 

  18. Unknown User (sharveyabhise)

    while executing Conditional step(single) for File exists. I set the "On evaluation failure" on "Fail the build". While running the project though the file doesn't exists the build status is SuccessfulHow to solve this issue?

  19. Unknown User (fsteff)

    With string compare, to access environment variables, ${VAR} usually works. However some variable names, such as ${VAR[4]} isn't working. 

    To access these kinds of variables, instead use ${ENV, var="VAR[4]"}