Creating and Editing Projects

In TeamCity, actual building tasks are carried out by build configurations and pipelines. However, both of them must be placed inside a project.

This topic illustrates different ways to create projects.

Root Project and Settings Inheritance

Before you begin, note that every TeamCity server includes a built-in, undeletable project called the Root project. All new projects are created as its children, but it cannot host build configurations and pipelines directly.

In TeamCity, child projects inherit many settings and entities from their parent, such as connections and cloud agent profiles. The Root project lets you take advantage of this concept and define server-wide resources. For example, you can create AWS cloud profile that spawns cloud agents accessible to all projects on the server.

You can navigate to the Root project settings by clicking the <Root project> breadcrumbs item in edit mode...

...or by going to the <your_server_URL>/admin/editProject.html?projectId=_Root URL directly. Note that since user permissions are project-based, only Root project administrators can edit its settings.

Create New Projects in TeamCity UI

New TeamCity projects can be added using corresponding sidebar buttons. The Create button next to the Projects menu item allows you to add top-level projects owned directly by the Root project.

To add a subproject of an existing project, click the identical button next to that project.

For a brand-new TeamCity installations, only From repository URL and Manually project creation options are available. You can get more options after you configure connections to VCS hosting providers.

From Repository URL

This option allows you to create a new project and a child build configuration in one go using a Git, Subversion, Mercurial, TFS, or Perforce repository (depot) URL. You can use any URL type:

A regular repository web link: https://github.com/Johndoe/my-sample-app
An HTTPS clone URL: https://github.com/Johndoe/my-sample-app.git
An SSH clone URL: git@github.com:Johndoe/my-sample-app.git

To start building a remote repository, follow the steps below.

On the new project page, click the From a repository URL tile.
Choose the authentication type.
Password / Access token
Enter a username and either a password or personal access token. For public repositories that do not require authentication to clone, you can leave both fields empty. If you later add features that need higher access (for example, write permissions for the Commit Status Publisher feature to display build statuses), you can configure authentication settings at that time.
SSH key
Available if the Repository URL is an SSH clone URL. Click Upload SSH key to add a private key, which will be saved in the parent project (parent project settings | SSH keys) and appear in the drop-down menu when configuring additional projects.
Learn more: SSH Keys Management
The next page contains mixed settings of both project and a build configuration owned by this project.
- Parent project — use this menu to change the project's parent.
- Project name and Build configuration name — public names visible in TeamCity.
- Default branch — the full name of a branch that will become a default one in TeamCity (for example, refs/heads/main). See the following article for more information: Default Branch.
- Branch specification — the set of rules that specify which repository branches TeamCity should track. The default refs/heads/* rule adds all repo branches to the watchlist. See the following topic to learn more: Working with Feature Branches.
The VCS root whose name is shown on this page stores most of the settings you entered: authentication settings, branch specification, and default branch. To edit them, navigate to project settings | VCS Roots.
- What are VCS Roots
- Configuring VCS Roots
Click Proceed. At this stage you have already created a project and its child build configuration, and now edit configuration settings. TeamCity opens the Add build step so you could add actual functionality to your configuration and start building or testing a remote repository. Refer to this article for more information on build steps.

Manually

This option allows you to create a completely blank project.

On the new project page, click the Manually tile.
Specify initial settings for your new TeamCity project:
- Parent project — use this menu to change the project's parent.
- Name — the public project name.
- Project ID — becomes a part of the project URL, and used to access this project in REST API calls, Kotlin DSL settings, and more. You can leave the default value which is assembled from parent project IDs and this project's truncated name.
- Description — the optional project description.
Click Create. You will end up with an empty project. Repeat the steps above to add subprojects to it, or start adding build configurations and pipelines.

From a Configured Connection

If a TeamCity project stores a configured connection to a VCS provider, it can use this connection to quickly set up all authentication settings and retrieve a list of remote repositories. This is the most convenient way to create multiple projects targeting different repositories stored under the same hosting provider.

First, you will require a connection. In this article, we will add a connection to GitHub and use it to add a project targeting a GitHub-hosted repository. See the Configuring Connections article for more information on connections to other VCS providers.

Add a connection

Open parent project settings. If you want a future connection to be available for any project created on this server, modify Root project settings. Otherwise, start with adding a manually created blank project.
Navigate to the Connections tab and click Add Connection.
TeamCity supports two GitHub authentication methods: OAuth 2.0 and GitHub App. In this walkthrough, we will use an automatically configured GitHub App, which requires no customization and takes less than a minute to set up. To learn more about both connection types, refer to this article: GitHub connections.
Choose the GitHub App as the connection type and click Create App.
TeamCity will redirect you to GitHub to approve the App, choose its installation location (personal account or organization), and optionally restrict its repository access. You can review and edit the TeamCity-configured App anytime via GitHub Settings | Developer Settings | GitHub Apps or uninstall it on GitHub Settings | Applications page.
After installing the App, you will return to TeamCity, where values for all connection settings (App ID, client ID, client secret, and others) will already be filled in. Click Test connection to verify the setup, then Save to complete it.

Once the connection is configured, you will see a new option on the Create project page.

Create a project

Click the From GitHub App tile. If you're using the new connection, TeamCity will ask you to sign in.
TeamCity will show a list of repositories accessible via the underlying connection. Use the search panel to find the desired repository, then click it to continue.
Creating projects using a VCS connection takes care of all authentication-related settings. You only need to complete steps 3 and 4 of the From Repository URL process.
- Parent project — use this menu to change the project's parent.
- Project name and Build configuration name — public names visible in TeamCity.
- Default branch — the full name of a branch that will become a default one in TeamCity (for example, refs/heads/main). See the following article for more information: Default Branch.
- Branch specification — the set of rules that specify which repository branches TeamCity should track. The default refs/heads/* rule adds all repo branches to the watchlist. See the following topic to learn more: Working with Feature Branches.
The VCS root whose name is shown on this page stores most of the settings you entered: authentication settings, branch specification, and default branch. To edit them, navigate to project settings | VCS Roots.
- What are VCS Roots
- Configuring VCS Roots
Click Proceed. At this stage you have already created a project and its child build configuration, and now edit configuration settings. TeamCity opens the Add build step so you could add actual functionality to your configuration and start building or testing a remote repository. Refer to this article for more information on build steps.

Create New Projects in Kotlin DSL

The following Kotlin code creates a project with two subprojects.

object MyProject: Project({
   name = "Main"
   description = "The main project"

   subProject {
      id("AllTests")
      name = "Subproject for different kinds of tests"
   }

   subProject {
      id("Packages")
      name = "Subproject for packages"
   }
})

See these articles for more information:

Create New Projects From REST API

The following request creates a new empty TeamCity project owned by the specific parent project.

export TEAMCITY_SERVER_URL="<Your TeamCity Server URL>"

curl --location $TEAMCITY_SERVER_URL'/app/rest/projects' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your TeamCity Access Token>' \
--data '{
    "name": "New Project from REST",
    "parentProject": {
        "locator": "id:Parent_Project_ID"
    }

See the following REST API documentation article for more information: Create and Delete Projects.

Manage Projects

You can view all available projects and subprojects on the Projects page listed in the alphabetical order by default. Administrators can customize the default order.

When you select a project from the list, TeamCity displays the Project Home page where you can preview its nested build configurations and recent build results. To access the project's settings, click the corresponding toggle in the top right corner to switch to the edit mode.

To copy, move, delete or archive a project, use the Actions menu in the upper right corner of the project settings page.

These options are not available for the Root project.

Copy a Project

Invoke the project Actions menu and click Copy project.... Projects can be copied and moved to another project by project administrators.

A copy duplicates all the settings, subprojects, build configurations, and templates of the original project, but no data related to builds is preserved. The copy is created with the empty build history and no statistics.

You can copy a project into the same or another parent.

On copying, TeamCity automatically assigns a new name and ID to the copy. It is also possible to change the name and ID manually.
Selecting the Copy project-associated user, agent and other settings option makes sure that all the settings like notification rules or agent's compatibility are exactly the same for the copied and original projects for all the users and agents affected.

You can also opt to copy build configurations build numbers.

Move a Project

Invoke the project Actions menu and click Move project....

When moving a project, TeamCity preserves all its settings, subprojects, build configurations/templates, and associated data, as well as the build history.

Archive a Project

Invoke the project Actions menu and click Archive project.... Refer the following help article to learn more about archiving TeamCity projects: Archiving Projects.

Bulk Editing IDs

Invoke the project Actions menu and click Bulk edit IDs.
The current project and build configuration IDs are displayed. You can modify or reset the IDs for all subproject, VCS roots, build configurations and templates. Click Regenerate to get new Ids automatically or edit them manually.
Click Submit.

Pause / Activate Triggers

Invoke the project Actions menu and click Pause / Activate... to temporarily disable triggers configured for multiple build configurations owned by this project.

Export a Project

Invoke the project Actions menu and click Export project... to move a project to a different TeamCity server.

Delete a Project

Invoke the project Actions menu and click Delete project....

When you delete a project, TeamCity will remove its .xml configuration files. After the deletion, the project is moved to the \< TeamCity Data Directory \>/config/_trash/.ProjectID.projectN directory. There is a configurable timeout (5 days by default) before all project-related data stored in the database (build history, artifacts, and so on) of the deleted project is completely removed during the next build history clean-up.

The TeamCity Data Directory /config/_trash/ directory is not cleaned automatically and can be emptied manually if you are sure you do not need the deleted projects.

Last modified: 02 July 2025