Pipeline Settings
This document explains core Pipeline settings available in the settings pane. To view available Pipeline settings, click the Edit toggle next to its title.
Repository
When you create a new Pipeline, TeamCity scans a VCS to gather a list of repositories that owned by or shared with you or your organization. Choose any repository to instantly create a Pipeline project that targets the default branch.
If you need to choose a different branch or specify which branches should be tracked or ignored, edit corresponding settings under the Repository section. You can use the asterisk ("*") character as a wildcard for any string. For example, the following setup allows TeamCity Pipelines to track all branches that start with "release-" (for example, "release-2023.05" or "release-2022.11"), and ignore the "sandbox" branch.
When viewing a Pipeline in a regular (non-edit) mode, use a selector in the page header to view/start runs for the target branch. To view all Pipeline runs regardless of a target branch, choose the <All branches> option.
You can click the side "+" button in the Repository section to add more repositories. This allows you to create Pipelines where different Jobs target different repositories. To select which repositories this particular Job should check out, toggle corresponding records in the Job settings pane.
Webhooks
When you create a new Pipeline from a remote GitHub, GitLab, or Bitbucket Cloud repository, TeamCity automatically sets up a webhook on the VCS side. This webhook listens for push and pull/merge request events, allowing TeamCity to receive near-instant notifications of changes and trigger builds promptly (provided the On new changes auto-run setting is enabled).
You can edit or remove this webhook in your repository settings. If the webhook stops working, TeamCity falls back to periodic polling to detect changes and start builds. TeamCity switches to polling if a manually triggered Pipeline reveals changes that were not reported via webhook.
Additionally, if no webhook events are received for about 8 hours, TeamCity performs a manual changes check. If changes are found, it assumes the webhook is malfunctioning and switches to periodic polling; otherwise, it waits another 8 hours before checking again.
YAML Storage Location
You can choose whether an .yml configuration file with your pipeline settings should be stored directly on the TeamCity Pipelines server, or in the VCS. See this article for more information: Working with YAML.
Parameters
Parameters are name-value pairs. Using aliases instead of raw values allows you to:
reuse values across build steps;
modify build behavior by changing parameter values without editing actual scripts or settings;
hide raw values for clarity or security.
When TeamCity encounters the %parameter_name% syntax, it inserts the corresponding parameter value instead.
In the Create a Multi-Job Pipeline tutorial, Job #2 runs the following script:
If you create the "DockerRepo = myusername/myrepositoryname" and "ImageName = mycustomtag" parameters, you can rewrite this script as follows:
Not only does this modification shorten your script body and make it more readable, but it also allows you to keep both values easily accessible. Should you require to change the repository or image name, you can do so from the Pipeline settings pane without tweaking script commands.
Parameter Levels and Scopes
You can define a parameter on a Job or Pipeline level. Job parameters are available only for this Job, whereas Pipeline parameters can be used by all of its child Jobs.
Pipeline parameters are mainly designed to be referenced in Pipeline, Job, and Step settings. For example, you may store the name of a default branch in a Pipeline parameter.
Job parameters are typically used inside build scripts. For that reason, TeamCity automatically adds the
env.prefix to Job parameter names when you create them in the UI. This turns a Job parameter into an environment variable, accessible on the agent machine by any building tool.
The sample below illustrates a difference between a regular parameter and an environment variable: job_parameter is available on the agent machine directly, and so its value can be printed by a script. In turn, pipeline_parameter exists only in TeamCity and can only be reported via a parameter reference.
This default logic is not the one and only way to declare and use TeamCity parameters. You are free to add env. prefixes to Pipeline parameters and remove them from Job parameters.
Secrets
Secrets are parameters whose actual values are stored securely by TeamCity and hidden away from web UI, logs, YAML configurations, and other locations. Use secrets to reference sensitive information (passwords, keys, access tokens, and so on) as parameters.
Auto-Run Pipeline
This section allows you to set up triggers that automatically start new builds when the specified conditions are met.
Initially, only the On new changes option is present. When enabled, this option forces new builds to start whenever new changes in the remote repository are detected.
In addition to this trigger, you can schedule new builds to start at any given time. To do so, click the plus icon and specify the building schedule.
Integrations
Integrations are access points for 3rd-party services used by Jobs. Currently, you can set up the following integration types:
Docker — allows Jobs to log into private imag
NPM — allows Jobs to access NPM registries
Unity — required to build Unity projects using the Unity runner
Once an integration is set up, any Job owned by this pipeline shows this integration under its settings. Use a toggle switch to allow a Job to use the corresponding integration. Note that you can also add new integrations when editing Job settings — these will be propagated to pipeline settings and become available for other Jobs in the same project.
Docker
This integration allows you to sign in to your DockerHub account before a Job starts and log out when it finishes. For instance, this can be necessary if a Job calls the docker push command to upload an image to a DockerHub repository. See this tutorial for the example: Create a Multi-Job Pipeline.
NPM
Allows Jobs to access a private npm registry during a build (for example, to download a package).
Connection settings:
Setting | Description |
|---|---|
Scope | The npm user/organization's scope to associate with the connected registry. If you want to use multiple registries per project, you need to specify a scope for each of them. Leave empty if you want to use only one registry in this project. It will be used by |
Registry URL | The npm registry URL in the following format: |
Access token | The token, if it is required to access the registry. Leave empty for anonymous access. Note that token-based authentication could differ depending on a registry type. See instructions for npm Enterprise, Space Packages, or GitHub Packages. |
Unity
Specify your account credentials and enter your licence key. This integration is required to run builds using the Unity runner and should be enabled in every Pipeline that uses this runner.