TeamCity Meta-Runners: Reuse Build Steps with Parameterized Runner Types

Originally published on 2015-02-24; fully revised and updated.

TeamCity Meta-Runners let you convert repeated build logic into reusable runner types with configurable parameters. This is especially useful for teams managing many similar build configurations and wanting less duplication, fewer copy-paste errors, and more consistent CI behavior.

Official reference: https://confluence.jetbrains.com/display/TCD9/Working+with+Meta-Runner

What Meta-Runners solve in TeamCity

A standard build runner can execute a task in one build configuration. A Meta-Runner goes further: it packages one or more build steps and exposes parameters so the same logic can be reused in many configurations. This is ideal when multiple pipelines repeat the same deployment, packaging, or environment setup sequence.

• Reduce duplicated step definitions across build configurations.
• Expose configurable inputs (for example remote URLs) as parameters.
• Keep behavior consistent while allowing per-configuration values.

Meta-Runners vs templates vs copied steps

Workflow: extract once, reuse across configurations

flowchart TD
    A[Identify repeated build steps] --> B[Replace hardcoded values with TeamCity parameters]
    B --> C[Validate the original build configuration]
    C --> D[Use Extract Meta-Runner in settings]
    D --> E[Review generated steps and parameters]
    E --> F[Save Meta-Runner at project level]
    F --> G[Add new build step using Meta-Runner type]
    G --> H[Set parameter values per configuration]
    H --> I[Run build and verify output]

Step 1: Parameterize the build step before extraction

The original example deploys to Heroku with a command-line runner. To make it reusable, replace hardcoded values with a build parameter such as %heroku.remote%.

git remote add heroku %heroku.remote%
git push heroku masterCode language: CSS (css)

Define heroku.remote in the build configuration parameters so each configuration can provide its own remote target.

Step 2: Extract the Meta-Runner

• Open the build configuration settings that contains the reusable steps.
• Use the Extract Meta-Runner action from the configuration UI.
• Provide a clear name (this appears later in the Runner type list).
• Save and review the generated Meta-Runner under project-level Meta-Runners.

Meta-Runners are represented as TeamCity XML configuration and can be edited from the web interface to keep only required steps and parameters.

Step 3: Use the Meta-Runner in other build configurations

• Create or edit a build step in another configuration.
• Select the extracted Meta-Runner in Runner type.
• Set parameter values for that configuration (for example a different remote).
• Save and run the build to confirm behavior matches the original step set.

# Example per-configuration parameter value
heroku.remote=git@heroku.com:my-team-app.gitCode language: PHP (php)

Operational notes for Heroku-style git deploys

The original example uses git remote push over SSH from a TeamCity agent. This requires agent-side SSH key setup and is shown as a Meta-Runner illustration, not necessarily as a production deployment pattern. The original source also mentions heroku-headless as an alternative approach.

Common pitfalls and best practices

• Do not hardcode environment-specific values. Always expose them as parameters.
• Keep Meta-Runners focused. Prefer small, reusable step groups over very large all-in-one runners.
• Name parameters clearly. Use predictable keys so teams understand required inputs quickly.
• Review defaults carefully. Remove unsafe defaults in Meta-Runner XML when accidental reuse could cause wrong deployments.
• Version and document usage. Track where each Meta-Runner is used to avoid breaking downstream configurations during edits.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.