Configuring Build Steps

Each build step 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 step based on your project's needs:

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.

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.

Recipes 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
  }
  // ...
})

Agentless build steps are steps that can run without a build agent attached, in an external software.

Normally, a running build occupies a build agent until the very finish, even if its final steps are executed outside TeamCity. However, if a build does not need its agent for some remaining steps, it can detach from this agent. The agent becomes available and can be instantly assigned to another build.

This approach allows saving agents' work time and is optimal for configurations that use third-party tools for finalizing a build: for example, to run numerous tests or deploy a project. Such a build can finish outside TeamCity; the TeamCity server will detect its status reports directly, without using an agent as a mediator.

Let's consider an example build that consists of three steps: compilation, testing, and deployment. All of them are processed by an agent even though the deployment step is actually performed by the external software. The agent is just polling the external software and reporting build statuses to the TeamCity server.

With the agentless approach, the agent does not need to handle the final deployment step and can run other builds from the queue. The TeamCity server will catch the following reports directly from the external tool.

See also: Detaching Build from Agent

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.

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.

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

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