Create and Edit Pipelines

Pipelines vs Build Configurations and Chains

Before we dive into creating pipelines, it’s important to understand the differences between build configurations and pipelines and when to use each. Note that once created, you cannot convert a pipeline (or any of its jobs) into a build configuration, and vice versa. See the Limitations and Special Notes section for more information.

Parents

Both build configurations and pipelines are owned by TeamCity projects. Each project can have an unlimited number of configurations and pipelines.

Children

• A build directly owns its build steps.

• A pipeline owns jobs, which in turn own regular build steps.

Supported VCS types

• Classic TeamCity build configurations support Git, Subversion, Mercurial, TFS, and Perforce, with integrations for major VCS providers like GitHub, GitLab, Bitbucket, Azure, and others.

• TeamCity Pipelines offer built-in integrations with GitHub, GitLab, and Bitbucket Cloud. Other Git repositories can be connected via direct URLs. Subversion, Mercurial, TFS, and Perforce are not currently supported.

Execution mode

• Pipelines always run from start to finish, executing all jobs unless interrupted by errors like compilation failures or connection issues.

• Build configurations support conditional step execution. For example, you can add a step that runs only if a previous one fails.

Dependencies

• Currently, pipelines support dependencies only between jobs within the same pipeline and cannot be linked into a larger sequence.

• Build configurations can form build chains across different TeamCity projects.

Configuration as code

Both pipelines and build configurations can store their settings as code, right next to your project source code. Both entities support branched settings, meaning each repository branch can have its own configuration file.

• Build configurations store their settings in XML or Kotlin DSL format. You cannot edit these files from the TeamCity UI.

• Pipelines store their settings in YAML which can be edited directly in TeamCity.

Kotlin DSL support is planned for future pipeline versions. However, there are no current plans to add YAML support for build configurations.

Limitations

• Build configurations are core TeamCity components, offering extensive features and customization options.

• Introduced in TeamCity 2025.07, Pipelines focus on providing the most intuitive way to design CI/CD workflows. However, they currently lack some of the functionality available in build configurations. For example, they do not support the majority of build steps and have no additional build features.

In summary, while both pipelines and build configurations are owned by projects, they serve different needs. Pipelines are ideal for simpler CI/CD workflows in smaller projects (typically up to 10–15 builds). Choose build configurations instead if:

• Your project involves more complex workflows than 10–15 sequential builds.

• You are an experienced user who needs advanced features (such as Build Approval) not yet available in pipelines.

• You require fine-grained control over which build chain configurations run, when, and how.

Create and Set Up Pipelines

To add a pipeline to a project, use the + button in the project header or TeamCity sidebar.

TeamCity will ask you to choose a remote repository that will be processed by this pipeline: you can choose an existing Git VCS root, a supported connection to a VCS hosting, or enter a Git URL manually. Default branch and branch specifications follow the same rules as regular build configurations, see Default Branch and Common Specification Syntax for more information. Note that if you select an existing root, branch settings will be disabled — modify root settings to edit them.

Every new pipeline has an empty job. You can click a job tile to view its settings, or click a corresponding area to add new jobs.

To view global pipeline settings, click a highlighted area in the visual editor.

To arrange pipeline jobs in the required order, select a job and check its upstream jobs in the Dependencies section. You can also use the visual editor to drag and drop a line from one job side to another.

See TeamCity Pipelines for more information on basic operations.

Job Outputs

Pipelines aim to streamline the user experience and present TeamCity concepts in a more accessible way. A key example is how they handle build results shared with end users and downstream jobs.

In classic TeamCity, files produced during a build and the parameters calculated along the way are mostly treated separately.

• Files are published as artifacts using paths defined in the build configuration settings. These artifacts appear on the Build Results Page page and can be downloaded by users or passed to other configurations via manually configured artifact dependencies.

• Parameters can be accessed by external configurations using the dep.<source_config_ID>.<parameter_name> syntax. In earlier versions, project administrators had no clear way to see which external configurations relied on their parameters, making it easy to unintentionally break CI routines used by other teams. Starting with TeamCity 2025.03, reusable parameters are now defined explicitly as output parameters, separate from standard "input" parameters intended for use only within their parent project.

Pipelines offer greater transparency by letting you manage both artifacts and parameters in a single, centralized interface. Click a job to open its settings, and expand the Job Outputs section. From here, you can mark any parameter or a file as an output.

Shared Files

Jobs can share files produced during a run. These files can be shared with either downstream jobs or TeamCity users (or both).

• Files shared with downstream jobs. In this case, jobs that follow the current one can import shared files and use them in their own scripts.

  The sample below illustrates a three-job pipeline whose jobs work with a file created and shared by the first job.

  jobs: Job1: name: Create file steps: - type: script script-content: touch output.txt files-publication: - path: output.txt share-with-jobs: true publish-artifact: false Job2: name: Modify file dependencies: - Job1: files: - output.txt steps: - type: script script-content: 'echo "Modified by Job #2" >> output.txt' Job1_2: name: Print file dependencies: - Job2 steps: - type: script script-content: cat output.txt

  Shared files are displayed as hidden artifacts in the ".shared_files.zip" archive.

• Files shared with users (artifacts). These are identical to build artifacts produced by classic build configurations. TeamCity shows artifacts in the Artifacts tab of a run results page.

To choose who a job should share a file with, tick related checkboxes under the job's Outputs section entry.

Dependencies

Another classic TeamCity concept reworked in Pipelines is dependencies. In Pipelines, snapshot and artifact dependencies are merged in a single option. Click a job to view its settings, choose which jobs should precede it, and decide whether you want this job to import their outputs.

You can also choose whether to import files by clicking a dependency line in the visual editor.

Webhooks

Classic TeamCity supports two methods for detecting repository changes: periodic polling and webhooks. While webhooks offer near-instant updates and lower server load, they require manual setup. For more information, see the Collecting Changes section.

Pipelines use webhooks by default as a faster and more efficient alternative to the polling mechanism. When you create a pipeline from a connection, TeamCity automatically registers a webhook in your repository settings. Polling remains as a fallback if the webhook is removed or fails to deliver updates.

Publish Run Statuses to VCS

Commit Status Publisher is one of the most popular TeamCity build features that communicates build statuses back to the VCS side. If you create a pipeline via a connection, this integration is available automatically.

The figure below illustrates TeamCity run statuses reported to the repository page on GitHub.

You can click the status icon to open the detailed description. The Details link leads to the corresponding pipeline run on the TeamCity server.

To disable this integration, click a pipeline to edit corresponding repository settings and toggle Publish status to repository off.

Limitations and Special Notes

TeamCity Pipelines are in early access and, while built on core TeamCity functionality, currently lack some features available in classic build configurations. We plan to expand the Pipelines toolset and add the most requested features in future releases.

Build steps

TeamCity pipeline jobs support three dedicated build steps for Maven, Gradle, and Node.js.

While other step types from classic build configurations are not yet supported, the Script step (equivalent to Command Line in classic TeamCity) offers a flexible alternative. For example, instead of using a .NET build step, you can add a Script step to run the dotnet build command.

Connections

TeamCity Pipelines currently support GitHub OAuth, GitLab, and Bitbucket Cloud connections.

Note that you do not need configured connections to create pipelines, you can do so from any Git repository URL.

VCS roots

Pipelines use VCS roots internally but present a simplified Repositories section instead of exposing VCS root settings directly. As a result, options like clean and checkout policies, custom polling intervals, and submodule handling are not configurable through the pipelines UI.

However, you can still create and configure a VCS root in the classic TeamCity UI, then create a pipeline from this root.

Build features

Pipelines are designed to offer the simplest, most user-friendly way to set up CI/CD routines. To support this goal, we are working on integrating key functionality directly into pipelines, avoiding the need for separately configured build features.

For example, the Commit Status Publisher is enabled automatically is enabled automatically when using connections, and registry connections are managed as Integrations within pipeline and job settings (rather than through separate Docker Registry Connections and NPM Registry Connection build features).

While traditional build features are not supported in pipelines, we are committed to bringing the most commonly used capabilities into the pipeline experience through more streamlined alternatives.

Triggers

TeamCity Pipelines currently support two types of triggers that allow CI routines to start automatically:

• Schedule trigger that starts new runs on the given date and time.

• VCS trigger that starts runs on new code changes.

Both are configured in the Auto-Run Pipeline section of pipeline settings.

Other trigger types (for example, the Finish build trigger or GitHub checks trigger are currently not supported).