The Power of Meta-Runner – Custom runners with ease

Posted on by Maarten Balliauw

TeamCity comes with a series of Runners out of the box which offer support for different functionalities such as MSBuild, Ant, Code Inspections, Gradle support, etc. In addition to these, there are a variety of runners that are supported via plugins, from FTP uploads to Grails and other things.


What happens when you want to perform some operation that is not supported via a runner? We could use the Command Line runner or build or own plugin. Each have their own benefits and disadvantages. The first one is quite straightforward, but the second offers more flexibility and a better user experience. TeamCity 8 introduced a third option: Meta-Runners.

Meta runners allow us to reuse build steps by representing them as a native TeamCity runner. In other words: we can extract configured build steps into Meta-Runners and reuse them in other build configurations. A good example are the PHP Meta-Runners from the Meta-Runner Power Pack. While TeamCity doesn’t come with PHP-specific runners, we have extracted some build steps into Meta-Runners that do make it easy to do Continuous Integration with PHP.

The following video demonstrates creation of a Meta-Runner:

Voilà! With just some clicks, we’ve created a new runner that we can re-use in other projects and build configurations.

Assumed FAQ

Guessing some of the questions that might come up, let’s try and address them:

1. Do I need a script file to create Meta-Runners?

No. You can base a Meta-Runner off of any existing runner. The UI is defined by the Build Parameters you create. It is important to note however that anything the Meta-Runner uses (for example a specific runtime or executable) should be available on the agent. One way of doing this is adding a step in the build process to prepare the environment, downloading any external dependencies. The Meta-Runner Power Pack contains an example Meta-Runner which uses Ant to download a file from a given URL.

2. Do Meta-Runners belong to the Root Project or a specific Project?

They can belong to either of them. In this example, we created it at the project level, but you can also create it at the root project level.

3. How do I delete them?

They are located on a new tab under the Project Settings.


4. Are there any limitations?


  • When extracted the runner, via the UI you cannot control which steps to extract. All steps are extracted.
  • Extract meta-runner UI does not allow to re-order the parameters. However, once meta-runner is extracted you can reorder them manually in the resulting xml file.

5. Sounds cool, but which Meta-Runners can I build?

Anything, really. Whenever it feels you’re duplicating build steps across build configurations, they are perfect candidates to extract a Meta-Runner. We already have some Meta-Runners that can be used in the Meta-Runner Power Pack. Feel free to contribute yours if they may be of use for others!

Try this and the other TeamCity 8 features and give us some feedback through the comments below!

Happy building!

Comments below can no longer be edited.

2 Responses to The Power of Meta-Runner – Custom runners with ease

  1. GitHubFlowVersion TeamCity MetaRunner | Robert Daniel Moore's Blog says:

    March 22, 2014

    […] other day I created a TeamCity Meta Runner that allows you to run GitHubFlowVersion against an MSBuild file. I thought I’d share it […]

  2. A Step by Step Guide: Create a custom TeamCity MetaRunner to notify NewRelic that a new deployment has occurred. | JetBrains TeamCity Blog says:

    June 19, 2014

    […] Balliauw has written a great introductory post on creating MetaRunners and I would strongly recommend you read that post to give you a good grounding in what they are and […]


Subscribe for updates