Configure and Run Your First Build

Create your first project

You can create a project in TeamCity in several ways: automatically from a repository URL, from a VCS connection, or manually. This tutorial focuses on the easiest method — creating a project from a repository URL. Simply provide your repository path, and TeamCity will scan it, detect build steps, and suggest configuration settings.

Each TeamCity installation includes a default Root project, which contains all other projects. Your first project will be added as a child of this Root. Follow these steps to create it:

1. Open the Projects tab and click " + ".

   

2. Enter a project name and optional description. You can leave the autogenerated Project ID as is.

   

3. A TeamCity project doesn’t perform builds itself — it serves as a container build configuratons and pipelines. Projects only help you organize related builds, manage permissions, and share resources such as connections and build parameters.

   After saving the project details, TeamCity will open the Set up your build page. Here you can choose to create a build configuration or a pipeline. For this tutorial, select a classic build configuration.

   

4. From the dropdown, select Connect new repository | Any Git URL from the drop-down menu.

   As you add more projects, you’ll gain access to other creation options. For example, creating from an existing VCS root or selecting a repository via an authenticated VCS connection.

5. Paste your repository URL. TeamCity supports Git, Subversion, Perforce, Azure, and Mercurial( all supported URL formats are listed here). For the sample project, use:

   https://github.com/JetBrains/Maven-Configuration-TeamCity-Samples

   This is a public repo, so you can choose HTTPS | Anonymous authentication. For private repositories or when write access is needed (for example, to post build statuses), select a different authentication method. See Creating and Editing Build Configurations for details.

   

6. After you click Proceed, TeamCity will locate the repository, check its branches, and prompt you to select the default one. You can also enable automatic build triggers for new commits.

7. Click Create to finish the initial setup. You now have a project with a child build configuration, and are looking at build configuration settings. Use the Settings button in the top right to switch between "Edit" (modify configuration) and "View" (review build history) modes.

   You can run the build configuration immediately. A TeamCity agent delegated with this build will fetch the sources, but since no build steps exist yet, the build will end quickly. Let’s add some of these steps now.

8. In configuration settings, open the Build Steps tab. Here you define the actions your configuration performs when triggered.

   Click Auto-detect build steps to let TeamCity scan your repository. For the sample project, it will suggest two Maven steps. Select the one that runs clean test for the ch-simple/pom.xml file and click Use selected.

Congratulations! You created your first TeamCity project and build configuration. You can now run the build and tweak configuration settings as needed.

Run your first build

To run builds in TeamCity, you need build agents. A fresh TeamCity server, installed as described here, has one registered build agent that runs on the same computer. Let's use this agent to run a build on the sample project.

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

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:

Tweak your build configuration settings

You might want to configure the following settings first:

• paths to build artifacts

• automatic triggers

• a custom pattern for a build number

For other settings, see this chapter.

Artifacts

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:

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

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:

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

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:

Takeaway

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.