TeamCity On-Premises 2021.1 Help

Configure and Run Your First Build

In TeamCity terms, a build is a process that consists of one or more steps and performs a certain CI/CD job.

After you have installed and started TeamCity as described here, you are ready to configure and run your first build.

Run your first build

You can watch a quick video guide or read the full tutorial below.

Create your first project

Every TeamCity installation has the default Root project that will contain all the other projects you create. To add your first project, click Administration in the upper right corner of the TeamCity UI and then click Create project.

There are several ways to create a project in TeamCity: automatically from a repository URL, from a connection to a specific VCS, or manually. In this tutorial, we will focus on the default and easiest way – from a repository URL. You will only need to provide a path to your repository — TeamCity will scan it and suggest some settings and potential build steps.

  1. On the Create Project page, click From a repository URL and paste the URL of your project's source repo as Repository URL. It can be a Git, Subversion, Perforce, Azure, or Mercurial repository. All supported URL formats are listed here. To use our sample repo, enter:

    If access to your repository is restricted, enter the credentials as well.

    Create a project from a repository URL, Step 1

  2. Click Proceed and follow the wizard.
    TeamCity will identify the type of your repository, test the connection, and autoconfigure the repository settings, as well as suggest the project and build configuration names.

    Create a project from a repository URL, Step 2

  3. Click Proceed.
    TeamCity will scan your VCS repository and autodetect the build steps.

  4. Check the boxes of the suitable steps, and they will be added to the first build configuration of this project.

    Create a project from a repository URL, Step 3

Congratulations! You are now ready to run the first build based on the just created build configuration. You can go straight to running it and tweak its settings afterwards.

Run your first build

A fresh TeamCity server, installed as described here, has one registered build agent that runs on the same computer. Agents are responsible for running TeamCity builds, so let's use it to run the first one, based on our recently created configuration.

On the Build Configuration Settings page, click Run in the upper right corner:

Run a build

TeamCity will always assign a build to the first available and suitable build agent.

You will be automatically redirected to the Build Results page, where you can watch the build progress and review its results upon the build finish. You can also access your build configuration settings from this page and edit them as necessary:

Build results

Tweak your build configuration settings

You might want to configure the following settings first:

For other settings, see this chapter.


If your build produces installers, WAR files, reports, log files, and so on, you might want to publish them on the TeamCity server after finishing the build. You can specify the paths to such artifacts in Build Configuration Settings | General Settings. As you already have a finished build, the build agent has checked out the sources already. Next to the Artifact paths field, click the tree icon to open the checkout directory browser. You can select artifacts from this tree:

Artifact paths

TeamCity will place their paths into the text field, so you can modify them if necessary:

Modify the artifact paths

Save the build configuration settings. Now, when you run a build, TeamCity will put all the specified reports into an archive and publish them.

The Build Configuration Home page lists all run builds and allows viewing their artifacts:

Published artifacts

You can also view and download artifacts from the Build Results page:

Artifacts in build results

Read more details here.

Automatic Build Trigger

Automatic build triggering on a change in the repository is essential to any CI. TeamCity will add a VCS trigger automatically when creating a project / build configuration from a repository URL. You can also add it manually on Build Configurations Settings | Triggers page:

Add a trigger

Build Number Format

Each build in TeamCity has a build number, that is a string identifier. It is composed according to the pattern defined in Build Configuration Settings | General Settings (click Show advanced options to display it). If you leave the default value, the build number format will be maintained by TeamCity; the number will be resolved into a next integer value on each new build start. Or, you can customize the pattern as described here.


To configure a certain CI/CD job in TeamCity:

  1. Create a project from your source repository and adjust its main settings.

  2. Create a build configuration inside this project.

  3. In the build configuration settings, add build steps that will represent stages of the build.

  4. Set up other configurations settings. For example, add handy build features and automatic triggers.

After that, you can run a build based on the created configuration manually, or wait until it is triggered automatically, if any triggers are configured.

Last modified: 08 September 2021