Run Steps on Condition

In some cases, it doesn't make sense to run all steps in a job for every single code change. Automation lets you control which steps within a job must be run based on specific conditions. For example, you might want to run different build steps depending on which branch of the code is being built, or you might want to skip certain steps when a change is made to a non-critical part of your code.

To add a condition to a step, use the job.container.runIf (or job.host.runIf) parameter. The runIf parameter accepts a string value. If the value is an empty string, false, or 0, the step is skipped. In all other cases, the step is executed.

job("Example") {
    // To check a condition, basically, you need a kotlinScript step
    host(displayName = "Check branch") {
        kotlinScript { api ->
            // To pass the result of the condition to other steps, create a job parameter
            api.parameters["isMainBranch"] = (api.gitBranch() == "refs/heads/main").toString()
        }
    }

    container(displayName = "Check branch", image = "ubuntu") {
        // This step will run only if the branch is "main"
        runIf("{{ isMainBranch }}")

        // here goes your script
        // ...
    }
}

Conditional steps are a perfect match for the customizable job parameters. Based on the user input, you can decide which steps to run. For example:

job("Example") {
    parameters {
        // Users can choose the environment during the custom run
        text("environment", value = "dev") {
            options("prod", "pre-prod", "dev")
        }
    }

    host(displayName = "Check environment") {
        // Check if the environment is prod
        kotlinScript { api ->
            api.parameters["is-prod"] = (api.parameters["environment"] == "prod").toString()
        }
    }

    container(displayName = "Conditional step", image = "ubuntu") {
        // Run only if the environment is prod
        runIf("{{ is-prod }}")

        shellScript {
            content = """
                echo I run only on prod
            """
        }
    }
}

Last modified: 15 December 2023