TeamCity Cloud 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 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 options to create a project in TeamCity:

  • From any repository URL (default)

  • From a repository of a specific VCS:

    • GitHub.com and GitHub Enterprise

    • Bitbucket Cloud
    • GitLab CE/EE and GitLab.com

    • Azure DevOps, or formerly Visual Studio Team Services

    You can find the example for GitHub.com below. Connection settings for other VCSs are detailed here.

  • Manually

In the first two scenarios, TeamCity will automatically suggest some settings and scan your repo to identify potential build steps.

Create project from repository URL

This is the fastest way to create a project.

  1. On the Create Project page, click From a repository URL and paste the URL of your project's source repository as Repository URL. The supported URL formats are listed here.
    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 build configuration.

    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 or tweak its settings beforehand.

Create project pointing to GitHub.com repository

The most convenient way to create projects is to integrate TeamCity with your VCS by a dedicated connection preset. All connections of a parent project are available to all its subprojects. That is, if you configure a connection to GitHub.com in the Root project settings, you will be able to instantly create projects from GitHub.com repos you have access to.

Let's start with creating a connection:

  1. On the Create Project page, click From a repository URL and then click the GitHub icon next to the Repository URL field.

  2. The Add Connection dialog opens (you can also open it from Project Settings | Connections).
    Here, you need to enter a client ID and secret for accessing your GitHub repo. But to get these parameters, you first need to register a new OAuth application for TeamCity in GitHub. Click register TeamCity to do this.

    Add a GitHub connection, Step 1

  3. The Register a new OAuth application page opens in GitHub. Make sure you are signed in as a GitHub user and follow these steps:
    • Specify the app name and homepage/callback URLs as declared in TeamCity. Click fromGH0_Copy.png to copy each parameter from TeamCity.

      Register a new OAuth application

    • Click Register application.

    • Scroll down and click Update application.
      You will see the client ID and secret granted to your new TeamCity application.

  4. Go back to TeamCity and, in the Add Connection form, enter the granted client ID and secret.

    Add a GitHub connection, Step 2

  5. Save your settings.

  6. Go back to Administration | Projects and click Create project.

  7. Select From GitHub.com and click Sign in to GitHub:

    Sign in to GitHub

  8. On the opened page, authorize the TeamCity application. The authorized application will be granted full control of private repositories and the Write repository hooks permission in GitHub.

The connection is now configured — you can continue with creating your project. After the app is authorized, TeamCity will list all the repositories available to your GitHub user. Start typing to filter the list and select the required repository:

Choose a repository

After you select the repo, TeamCity will verify the connection to it and open the Create Project page. It will propose the project and build configuration name. If necessary, you can modify them and click Proceed.

Then, it will scan your VCS repository and autodetect the potential build steps (it may take some time). Check the boxes of the suitable steps, and they will be added to the build configuration.

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

Create project manually

If you don't want TeamCity to autodetect build steps, you can create a project manually.

  1. On the Create Project page, click Manually. Specify the project's name, ID (autogenerated but modifiable), and an optional description.

    Create a project manually, Step 1

  2. Click Create.
    TeamCity will prompt to add at least one build configuration. Click Create build configuration.
    The configurations can be created automatically (similarly to creating projects) or manually as described below. If you select to do it manually, specify the build configuration name, ID, and an optional description.

    Create a project manually, Step 2

  3. TeamCity will offer to create and attach a new VCS root.

    A VCS root can be created automatically or manually. To create it manually, select a type of VCS from the drop-down menu (Git in the example below), specify the required information (name and URL), test your connection, and click Create.

    Create a project manually, Step 3

  4. Optionally, configure checkout rules. They can instruct TeamCity to exclude some directories from the checkout, or, if necessary, change the location where the checked out sources are stored on the build agent.
    You can also specify whether you want TeamCity to check out the sources on the agent or server. If you want to use agent-side checkout, note that it is not supported for some VCSs, and that you need to have a version control client installed on at least one agent.

  5. After the VCS root is created, TeamCity will display the build configuration settings. The first thing to do here is to configure build steps. You can either instruct TeamCity to scan your repository and detect them automatically, or configure them manually as described in this example.

  6. Click Add build step and select a convenient build runner from the drop-down menu.

    Selecting a build step

  7. Fill in the required fields and save the build step.

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

Run your first build

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 required:

Build results

Tweak your build configuration settings

You might want to configure the following settings first:

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:

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.

Last modified: 20 July 2021