Working with Meta-Runner

Using Meta-Runners Power Pack

Meta-runners Power Pack for TeamCity, available on GitHub, is a collection of meta-runners for various tasks such as downloading a file, triggering a build, tagging a build, changing a build status, running PHP tasks, and so on.

Each *MRPP_*.xml* file contains a definition of a single meta-runner. Download the required meta-runner (or copy its definition to a file) and install it as described in the section below.

Installing Meta-Runner

You can install a meta-runner using the TeamCity web UI. Alternatively, you can do it directly via the file system.

• To install a meta-runner via the Web UI, go to Project Settings | Meta-Runners, click Upload Meta-Runner, and select the meta-runner definition file. Save you changes.

• To install a meta-runner directly to the file system, put the meta-runner definition file into the <TeamCity Data Directory>\config\projects\<project_ID>\pluginData\metaRunners directory, where <project_ID> is the identifier of a project under which you want to place the meta-runner. If the metaRunners directory does not exist, create it manually.

  
  

  Once you place the file on the disk, TeamCity will detect it and load the meta-runner; no server restart is required.

If the meta-runner is loaded successfully, you will see it listed on the Meta-Runners page in the project settings; if you have appropriate permissions, you can modify the definition directly in the TeamCity UI.

The runner is now available in the list of build runners on the Build Configuration Settings | Build Steps page and is represented as a native TeamCity runner with a convenient UI.

A meta-runner placed into a project will be available to all its subprojects and build configurations. To make a meta-runner available to all projects, place it in the Root project.

Creating Meta-Runner

You can create a build configuration via the TeamCity web UI and extract a meta-runner from it or use the XML definition of an existing build configuration as a meta-runner.

Creating Your Own Meta-Runner from UI

Let us consider an example of creating a meta-runner.

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

1. Prepare a build configuration to test the build steps to be used in the 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 the 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 — since meta-runners do not include VCS roots of their origin configurations, a target configuration cannot take build.xml from the version control repository. 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 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.

If your meta-runner contains steps that need to access files and folders of a remote repository, do the following:

1. Go the settings of a build configuration that imports a meta-runner.

2. Switch to the Version Control Settings tab.

3. Click the Attach VCS root button.

4. In the Attach existing VCS root choose the same root your origin configuration uses.

5. Click Save at the bottom of the page and run your build configuration. Since it now has a connection to a VCS repository, build steps can access required files and are able to finish successfully.

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 by clicking the Actions button in the upper right corner of the Build Configuration Settings page and selecting the Extract meta-runner option:

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, under the name of the project it belongs to, 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 page:

When a meta-runner is extracted, all steps are 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 Project Administration | Meta-Runners and use the Edit option next to the meta-runner. The parameters will be shown in the same order as <param> elements in the XML definition. Definitions of meta-runners are stored in the <TeamCity Data Directory>\config\projects\<project_ID>\pluginData\metaRunners directory.

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 named as <runner_id>.xml where <runner_id> is the ID of this build runner. Install the meta-runner as described above.

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.

Creating Build Configuration from Meta-Runner

If you need to fix a meta-runner and test your fix, you can create a build configuration from a meta-runner, change its steps, adjust parameters and requirements, check how it works, and then use the Extract meta-runner action to apply the changes to the existing meta-runner with the same ID.

Launch Meta-Runners in Containers

Individual build steps comprise meta-runners have settings that allow TeamCity to run these steps inside Docker/LXC containers. Same settings are available for meta-runners themselves.

If you want all of your steps to be executed inside a required container, set up the required image on the meta-runner level. Container settings of individual steps have a priority over these meta-runner settings and allow you to run each step in its unique container.

Kotlin sample of a meta-runner that runs its steps inside "ubuntu" Linux container:

The XML markup for this meta-runner is shown below. Step #1 runs in the python:3.9.20-bullseye container. Step #2 has no personal container settings and runs inside the ubuntu container as defined in the Kotlin code above.