Build Step Execution Conditions

When configuring a build step, you can choose a general execution policy and, since TeamCity 2020.1, add a parameter-based execution condition.

Execution conditions make builds more flexible and address many common use cases, such as:

running the step only in the default branch
running the step only in the release branch
skipping the step in personal builds

You can quickly select any of the available common options in the build step Add condition menu:

Alternatively, select the Other condition option to add the parameter-based execution condition, which is a logical condition that takes on input any build parameter provided by the TeamCity server or agent.

For example, to run the build step only on the testbranch branch, you can test the value of the teamcity.build.branch parameter, as follows:

In the Kotlin DSL, you can check the teamcity.agent.jvm.os.name parameter to run the current build step only on Windows agents, as follows:

package _Self.buildTypes
import jetbrains.buildServer.configs.kotlin.*


object MyBuildConfig : BuildType({
    // ...
    steps {
        script {
            name = "Step 1"
            conditions {
                contains("teamcity.agent.jvm.os.name", "Windows")
            }
            // ...
        }
    }
})

The sample below illustrates how to utilize parameters that report step exit statuses to create a custom condition (step #3 runs only when step #2 fails and step #1 is successful.).

package _Self.buildTypes

import jetbrains.buildServer.configs.kotlin.*

object MyBuildConf : BuildType({
    steps {
        python {
            id = "Step1"
            // ...
        }
        python {
            id = "Step2"
            // ...
        }
        python {
            name = "Step3"
            conditions {
                equals("teamcity.build.step.status.Step1", "success")
                equals("teamcity.build.step.status.Step2", "failure")
            }
            // ...
        }
    }
})

If you declare multiple execution conditions, the build step will be executed only if all of them are satisfied in the current build run.

If you use parameter-based execution conditions in a build which belongs to a build chain, note that the parameter, used in a step condition, might change own value during the build. This might cause an unexpected source reuse in the whole build chain. To prevent this, consider disabling the "Do not run new build if there is a suitable one" option in the snapshot dependency of the build configuration that depends on the build with such condition. If this option is enabled, TeamCity will show the corresponding health report for the affected build configuration.

In this demo, we explore a use case when you need to run a given step only if the build runs in the specific environment. This can be easily achieved with build step conditions.

You can also read a recap of this tutorial in this blog post.

Last modified: 07 December 2023