TeamCity 2019.1 Help

Configure and Run Your First Build

After you have installed and started TeamCity as described here, the server is accessible locally on the default port (on Windows as http://localhost/, and on Linux/OS X as http://localhost:8111/) and has one registered build agent that runs on the same computer.

Now we can get building! This section describes how you can:

Create your first project

In TeamCity, there is the default <Root project> containing all other projects in TeamCity. To create a project, click the Administration link in the upper right corner and then click Create project. The Create Project page is displayed.

There are several options to create a project:

Create a project from a repository URL

This is the fastest way to create your first build.

  1. On the Create Project page, click From a repository URL and paste the URL of your project's repository into the Repository URL field. The supported URL formats are listed in VCS URL Formats.
    If required, specify your repository credentials.

    Create a project from a repository URL, Step 1

  2. Click Proceed and follow the wizard.
    TeamCity will do the rest for you: it will identify the type of the VCS repository, test the connection, and autoconfigure VCS 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 your build steps.

  4. Check the boxes of the steps and use them in your build configuration.

    Create a project from a repository URL, Step 3

    The selected build step is added to the build configuration.

Congratulations! You've configured your first build containing one build step. Now you can run your build and tweak its settings if necessary.

Create a project pointing to GitHub.com repository

  1. On the Create Project page, click From a repository URL and then click the GitHub icon next to the Repository URL field.
    Note that if one or more connections to GitHub are predefined for the parent project, TeamCity will suggest picking one of these connections to create a project from it. If not, proceed with Step 2.

  2. The Connections page with the Add connection dialog opens. It provides the parameters to be used when registering your TeamCity application in GitHub service.
    Click the register TeamCity link.

    Add a GitHub connection, Step 1

  3. The GitHub page opens.
    You need to register TeamCity as an OAuth application in GitHub. The following steps are performed in your GitHub account:

    • Sign into your GitHub account. On the Register a new OAuth application page specify the name (and an optional description), homepage URL, and callback URL as provided by TeamCity. Use the fromGH0_Copy.png icon to copy the required parameters.

      Register a new OAuth application

    • Click Register application.

    • Scroll down and click Update application.
      The page is updated with the Client ID and the client secret information for your TeamCity application.

  4. Continue configuring the connection in TeamCity: on the Add Connection page, specify the Client ID and the client secret.

    Add a GitHub connection, Step 2

  5. Save your settings.

  6. Next you need to authorize TeamCity in the VCS: go to the Project administration, click Create project, select From GitHub.com, and click Sign in to GitHub:

    Sign in to GitHub

  7. On the page that opens, 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 configured: you can continue with creating your project in TeamCity. All the repositories available to the user will be listed. Start typing to filter the list and select the required repository:

    Choose a repository

    TeamCity will verify the repository connection. If the —Āonnection is verified, the Create Project page opens. TeamCity will display the project and build configuration name. If required, modify the names and click Proceed.

  8. TeamCity will scan your VCS repository and autodetect your build steps (it may take some time). Check the boxes of the steps and use them in your build configuration.

  9. The selected build step is added to the build configuration.

Congratulations! You've configured the GitHub connection and your first build containing one build step. Now you can run your build and tweak its settings if necessary.

Create a project manually

You can create a project manually if autodetection of settings is not suitable for you.

  1. Click the Administration link in the upper right corner, then click Create project and select Manually. Specify the project's name, ID (autogenerated, modifiable), and an optional description.
    Click Create:

    Create a project manually, Step 1

  2. When a project is created, TeamCity prompts to populate it with build configurations. 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 (autogenerated, modifiable), and an optional description.

    Create a project manually, Step 2

  3. TeamCity offers to create and attach a new VCS Root: to be able to create a build, TeamCity has to know where the source code resides, and a VCS root is a collection of VCS settings (paths to sources, login, password, and other settings) that defines how TeamCity communicates with a version control (SCM) system to monitor changes and get sources for a build. Each build configuration has to have at least one VCS root attached to it. 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

    After you have created a VCS root, you can instruct TeamCity to exclude some directories from checkout, or map some paths (copy directories and all their contents) to a location on the build agent different from the default one. This can be done by means of checkout rules.
    You can also specify whether you want TeamCity to checkout the sources on the agent or server. Note that the agent-side checkout is supported not for all VCSs, and in case you want to use it, you need to have a version control client installed on at least one agent.
    After the VCS Root is created, the build configuration settings are displayed on the left.

  4. Now you can configure Build steps by selecting the corresponding setting on the left. You can either instruct TeamCity to automatically detect the build steps after scanning your repository or configure build steps manually as described in this example.
    Click Add build step and select a build runner from the drop-down menu.

    Selecting a build step

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

Congratulations! You've configured your first build containing one build step. Now you can run your build and tweak its settings if necessary.

Run your first build

Your build configuration currently has one build step, and you can now launch your first build by clicking Run in the upper right corner of the TeamCity web UI:

Run a build

You will be redirected to the build result page, where you can watch the build progress and review its results upon the build finishing. 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:

Artifacts

If your build produces installers, WAR files, reports, log files, and so on, and you want them to be published on the TeamCity server after finishing the build, you can specify the paths to such artifacts in the General Settings section of the build configuration settings. As you have a finished build, the build agent has the checkout sources already and the Artifact paths field has the checkout directory browser. You can select artifacts from the tree:

Artifact paths

TeamCity will place the paths to them into the input field, so you can modify them as needed:

Modify the arifact paths

Save your settings. Now when you run a build, TeamCity will put the required reports into an archive. The build configuration home page lists all builds that were run and enables you to view the available artifacts:

Published artifacts

You can also view and download artifacts from the build results page:

Artifacts in build results

More details are available in Artifact Paths.

Automatic Build Trigger

Automatic build triggering on detecting a change in the version control is essential to any CI. TeamCity will add a VCS trigger automatically when creating a project / build configuration from a URL or repository. You can also do it manually using the Edit Build Configuration Settings drop-down men, the Triggers page:

Add a trigger

Build Number Format

Each build in TeamCity has a build number, which is a string identifier composed according to the pattern specified on the General Settings page of your build configuration (the field is available on clicking the Show advanced options link). You can leave the default value here, in which case the build number format will be maintained by TeamCity and will be resolved into a next integer value on each new build start. More details are available in the dedicated section of our documentation.

Happy building!