You are viewing the documentation of TeamCity 8.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 9.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

A Meta-Runner allows you to extract build steps, requirements and parameters from a build configuration and create a build runner out of them. This build runner can then be used as any other build runner in a build step of any other build configuration or template.

Basically, a meta-runner is a set of build steps from one build configuration that you can reuse in another; it is an xml definition containing build steps, requirements and parameters that you can utilize in xml definitions of other build configurations. TeamCity allows extracting meta-runners using the web UI.

With a meta-runner, you can easily reuse existing runners, create new runners for typical tasks (e.g. publish to FTP, delete directory, etc.), you can simplify your build configuration and decrease a number of build steps.

All meta-runners are stored on a project level, so they are available within this project and its subprojects only, and are not visible outside. If a meta-runner is stored on the <Root project> level, it is available globally (in all projects).

Let us consider an example of creating a meta-runner. More examples of meta-runners are available on GitHub: see Meta-runner Power Pack for TeamCity 8.

To create a meta-runner, follow these steps (described below in more detail):

  1. prepare a build configuration to test the build steps we are going to use in our meta-runner,
  2. make sure the build configuration is working,
  3. extract a meta-runner to the desired project.

In this example, we will create a meta-runner to publish some artifacts to TeamCity with the help of corresponding service message.

Usually artifacts configured in a build configuration are published when the build finishes. However, sometimes for long builds with multiple build steps we need artifacts faster. In this example, we will create a runner which can be inserted between any build steps and can be configured to publish artifacts produced by previous steps.

Preparing Build Configuration

The first step is to prepare a build configuration which will work the same way as the meta-runner we would like to produce. Let us use the configuration with a single Ant build step: Ant can be executed on any platform where the TeamCity agent runs; besides, Ant runner in TeamCity supports build.xml specified right in the runner settings. This is important because our build configuration must be self-contained, it cannot take build.xml from the version control repository. So in our case the Ant step settings will look like this:

where artifact.paths is a system property. We need to add it on the Build Parameters tab of the build configuration settings:

Note that each parameter can have a specification where we can provide the label, description, type of control and specify validation conditions. Before version 8.0 this specification was used by the custom build dialog only. Now this specification is used by a meta-runner too.


Here the Ant build step is used just as an example. In the initial build configuration, you can use any of the available build runners (e.g. MSBuild, .Net process, etc.) and configure the settings, define the parameters for this build step. When you extract a meta-runner from this build configuration, all the settings defined in the build step, and all the build parameters will be added to the meta-runner.

Verifying Build Configuration Works Properly

Once the build steps and parameters are defined, we need to make sure our build configuration works by running a couple of builds through the custom build dialog:

Extracting and Using Meta-Runner

If the build configuration works properly, we can create a meta-runner using the Extract Meta-Runner button in the build configuration settings sidebar:

The Extract Meta-Runner dialog requires specifying the project where the meta-runner will be created. A meta-runner created in a project will be available in this project and all its subprojects. In our case the <Root project> is selected, so the meta-runner will be available in all projects.

We also need to provide the name, description and an ID for the meta-runner: the name and description will be shown in the web interface, an ID is required to distinguish this meta-runner from others.

Upon clicking the Extract button, TeamCity will take definitions of all build steps and parameters in this build configuration and create a build runner out of them.


Besides build steps and parameters, a meta-runner can also have requirements: if requirements are defined in the build configuration, they will be extracted to the meta-runner automatically. Requirements can be useful if the tools used by meta-runner are available on specific platforms only.

Once the meta-runner is extracted, it becomes available in the build runners selector and can be used in any build step just like any other build runner:

The current meta-runner usages can be seen at the project Meta-Runners tab:

When a meta-runner is extracted from the web interface, all steps will be extracted. If you need to reorder parameters or make some quick fixes in the runner script, you can edit its raw xml definition in the web browser: go to the Administration page of the project -> Meta-Runners and use the Edit option next to the meta-runner. The parameters will be shown in the same order as the <param> elements in the xml definition. Definitions of meta-runners are stored in the TeamCity Data Directory \config\projects\<project ID>\pluginData\metaRunners folder.

Creating Meta-Runner from XML Definition of Build Configuration

Alternatively, you can use the xml definition of an existing build configuration as a meta-runner. To do it, save the definition of this build configuration to a file in the TeamCity Data Directory\config\projects\<project ID>\pluginData\metaRunners folder. The file should be named as follows: <runner id>.xml, where <runner id> is the ID of this build runner. The server will detect this definition and will load it on the fly.

Since a meta-runner looks and works like any other runner, it is also possible to create another meta-runner on the basis of an existing meta-runner.

  • No labels