Migrating TeamCity meta-runners from XML to YAML recipes: approach and limitations – Support | JetBrains

Question

In TeamCity 2025.03, meta-runners were renamed to recipes. A recipe can be defined in the legacy XML syntax (the former meta-runner format) or in the newer YAML syntax. Existing XML meta-runners continue to work unchanged.

Is migrating recipes (meta-runners) from XML to YAML the recommended path, how can recipes referenced by many build configurations be migrated without breaking them, and what are the known limitations of YAML recipes compared to XML?

Answer

Is YAML the recommended format?

YAML is the recommended format for authoring recipes going forward, while XML remains supported for backward compatibility. The Introducing TeamCity Recipes announcement states: "While XML is still supported for backward compatibility, YAML is now the recommended format." Existing XML meta-runners keep working with no changes, and no XML deprecation date has been announced. Because of the step-type limitation described below, migration is best done selectively rather than as an all-at-once conversion.

Migrating recipes referenced by many build configurations

A build configuration references a recipe by the recipe id, which becomes the build step's runner type:

For an XML recipe, the id is derived from the definition file name.
For a YAML recipe, the id is taken from the name field inside the file.

To avoid breaking existing references, the YAML recipe must keep the same id as the XML recipe it replaces. When the id is unchanged, existing build steps continue to resolve the recipe.

Additional points:

There is no automatic XML-to-YAML converter. YAML recipes cannot be extracted from a build configuration; the .yml definition is written from scratch. Migration is a manual, per-recipe rewrite, and no official migration guide exists.
YAML recipe names have their own constraints: a standalone private recipe name is limited to 100 characters, using alphanumeric characters, dashes, and underscores. Existing meta-runner ids must fit these rules to be preserved.
Recommended approach: convert one recipe first in a test project, keep its id, confirm that every build configuration using it still resolves the step and runs, then roll out incrementally.

Known limitations of YAML recipes compared to XML

YAML recipe steps currently support only Kotlin Script, Command Line (script) steps, and other (nested) recipes. XML meta-runners can wrap any runner type (for example Maven, Gradle, .NET, Docker-based tool runners, or Ant). A meta-runner that wraps a non-script runner cannot be expressed directly in YAML; that step must be reworked into a script. For this reason, recipes whose steps are only script-based are the best candidates for YAML, while recipes wrapping other runner types remain in XML until YAML supports those step types.

Additonal information