Working with Meta-Runner
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):
prepare a Preparing-Build-Configuration,
In this example, we will create a meta-runner to publish some artifacts to TeamCity with the help of corresponding Build Script Interaction with TeamCity.
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.
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.
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 \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 \config\projects\<project ID>\pluginData\metaRunners folder. The file should be named as follows: <runner id>.xml, where <runner id> is the Identifier 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.