Configuring Build Steps

Once you have a TeamCity project with a build configuration within it, you can configure build steps. A build step (also referred to as a "job") is a task to be executed by a build runner. One build configuration can include multiple steps, executed consecutively.

Build steps are configured in the Build Steps section of the Build Configuration Settings page. This page allows you to:

Add new steps manually.
Autodetect steps by scanning the source VCS repository.
Copy and delete steps.
Temporarily enable/disable steps.

Choosing Build Runner for Your Task

Each build step is represented by a build runner and provides integration with a specific build or test tool. For example, calling a NAnt script before compiling VS solutions. You can add as many build steps to your build configuration as needed.

This video tutorial explains how to choose a build runner based on your project's needs:

Build Steps Execution

Build steps are invoked sequentially.

The decision whether to run the next build step may depend on the exit status of the previous build steps, the current build status, or execution conditions.

The build step is considered failed if (1) the build process returned a non-zero exit code and (2) the " Fail build if build process exit code is not zero " build failure condition is enabled (see Build Failure Conditions); otherwise, the build step is considered successful.

Note that the status of a build step and the build itself can be different. All build steps can be successful, but the build can fail because of another build failure condition — not based on the exit code (like failing a test). On the other hand, if a build step has failed, the build will fail too.

For the details on configuring individual build steps, refer to the respective pages inside this section.

Execution Policy

You can specify the step execution policy via the Execute step option:

Only if build status is successful — before starting the step, the build agent requests the build status from the server, and skips the step if the status is "failed". This considers the failure conditions processed by the server, like failure on test failures or on metric change. Note that this still may be not exact as some failure conditions are processed on the server asynchronously (TW-17015).
Only if build status is failed — same as above, but the agent skips the step if the build status is "success". This condition allows you to add steps that are executed only when a build fails. For example, you can run tasks that rollback the latest changes to the remote repository that introduced the issue.
If all previous steps finished successfully — the build analyzes only the build step status on the build agent, and doesn't send a request to the server to check the build status and considers only important step failures.
Even if some of the previous steps failed — select to make TeamCity execute this step regardless of the status of previous steps and status of the build.
Always, even if build stop command was issued — select to ensure this step is always executed, even if the build was canceled by a user. For example, if you have two steps with this option configured, stopping the build during the first step execution will interrupt this step, while the second step will still run. Issuing the stop command for the second time will result in ignoring the execution policy: the build will be terminated.

Since TeamCity 2020.1, you can also add granular execution conditions for build steps.

Bootstrap Steps

A bootstrap step is performed right after a build is triggered, before a build agent checks out source files. This allows you to add a runner (typically the Command Line one) that performs initial setup and ensures the following steps run as expected.

To enable bootstrap steps, first add the teamcity.internal.bootstrap.steps.enabled=true entry either to TeamCity Internal Properties or to the individual project (as this project's configuration parameter). This setting allows you to do the following:

Enable the Run during bootstrap option in step settings.
On the configuration's Build Steps page, click Reorder build steps and drag the required step before the "Preparation stage" block.

You can create a build configuration with a bootstrap step and turn this configuration into a template. Such template allows you to quickly create more configurations that perform required prerequisite actions before the actual building process starts.

Meta-Runners are considered as a single step and thus cannot be split into parts performed before and after a checkout.

To turn a regular step into a bootstrap one in Kotlin DSL, add a teamcity.step.phase parameter and set its value to "bootstrap".

object MyConfig : BuildType({
  // ...
  steps {
    script {
      name = "Disk prep"
      id = "simpleRunner"
      scriptContent = "echo 'Initial setup'"
      param("teamcity.step.phase", "bootstrap") // Bootstrap step
    }
    // Regular steps
  }
  // ...
})

Autodetecting Build Steps

TeamCity can scan the source VCS repository of a project and autodetect build steps in Node.js, Kotlin, Python, Ant, NAnt, Gradle, Maven, MSBuild, Visual Studio solution files, PowerShell, Xcode project files, Rake, and IntelliJ IDEA projects.

In Build Steps, click Auto-detect build steps, and then select the proposed steps you want to add to the current build configuration. You can change their settings afterwards.

When scanning the repository, TeamCity progressively searches for project files on the two highest levels of the source tree. When searching, it takes into consideration the extension of the files. For example:

PowerShell: .ps1
.NET: project.json, .proj, .csproj, .vbproj, .sln

If the detected steps have already been added to this configuration manually, TeamCity will skip those.

Step Status Parameters

TeamCity provides teamcity.build.step.status.<step_ID> parameters that report the status of the step with the given ID. Step IDs are shown below their names, and are editable only when you create them.

The available values of the teamcity.build.step.status.<step_ID> parameters are:

success — when a step finishes with no errors.
failure — when a step failed. This status is reported even when all build problems were muted.
cancelled — when a build was cancelled while this step was running.

The teamcity.build.step.status.<step_ID> parameters appear only after their corresponding steps finish, and are not available right from the moment a build starts. This means neither steps that are still running, nor skipped steps have their teamcity.build.step.status.<step_ID> parameters available.

You can check all step statuses in the Parameters Tab of the build results page...

...or via TeamCity REST API.

http://<SERVER_URL>/app/rest/builds/<BUILD_ID>/resulting-properties

You can utilize these parameters to create custom Build Step Execution Conditions.

Last modified: 18 September 2024