Working with YAML

TeamCity Pipelines supports the configuration-as-code approach: all pipeline settings are serialized into a YAML file that you can edit, share, store in a remote repository, and use to easily clone your projects.

Edit YAML Configuration

To view and edit an .yml file with all pipeline configuration settings, start editing your pipeline and use the Visual/YAML toggle in the main client area.

You can edit your pipeline directly in the YAML editor. The built-in syntax editor displays interactive autocomplete suggestions and hightlights invalid markup.

Store the Configuration File in VCS

The Repository section of Pipeline settings allows you to choose whether an .yml file with your pipeline settings should be stored on the TeamCity Pipelines server, or on the VCS side (next to the same source files your pipeline processes).

Select the in VCS repository option and TeamCity will commit the ".teamcity.yml" file to the root directory of a related repository. When it's done, a two-way synchronization will be enabled: all edits on the Pipelines side will be committed to this file and vice versa, editing the configuration file will alter your project.

You can sever this link at any time by toggling to the on TeamCity server mode. Should you re-enable the in VCS repository option later, TeamCity will check whether the current pipeline settings differ from those stored on the VCS side. If yes, TeamCity Pipelines will display a dialog that allows you to choose whether current settings should be discarded and replaced with those stored on the VCS side, or the configuration file on the VCS side should be updated to include your current settings.

Apply YAML Settings for New Pipelines

If you create a new pipeline from a repository that already stores the ".teamcity.yml" file in its root directory, TeamCity will display a message that allows you to either import existing settings, or start a new project from scratch.

For both options, you can toggle the in VCS repository / on TeamCity server selector.

Import option / Selector value	Import pipeline from .teamcity.yml	Create a new pipeline
in VCS repository	The new pipeline applies settings from a remote repository, and the two-way synchronization is enabled. Note that if you have other projects that target the same repository, changes from one project can be propagated to other pipelines via this shared YAML file.	A new empty pipeline is created, and its settings are pushed to the remote repository. This workflow overwrites the contents of the existing .teamcity.yml file (replaces them with new project settings).
on TeamCity server	The new pipeline imports settings from the remote repository once, and then ignores the remote YAML file. You can manually edit pipeline settigns to enable the VCS-TeamCity settings synchronization.	An empty standalone pipeline that ignores remote setting is created.

Import option / Selector value

Import pipeline from .teamcity.yml

Create a new pipeline

in VCS repository

The new pipeline applies settings from a remote repository, and the two-way synchronization is enabled.

Note that if you have other projects that target the same repository, changes from one project can be propagated to other pipelines via this shared YAML file.

A new empty pipeline is created, and its settings are pushed to the remote repository.

This workflow overwrites the contents of the existing .teamcity.yml file (replaces them with new project settings).

on TeamCity server

The new pipeline imports settings from the remote repository once, and then ignores the remote YAML file.

You can manually edit pipeline settigns to enable the VCS-TeamCity settings synchronization.

An empty standalone pipeline that ignores remote setting is created.

Last modified: 18 September 2024