JetBrains · Valrravn · Oct 27, 2025 · Oct 14, 2025 · Oct 16, 2025 · Oct 16, 2025
diff --git a/images/attach-and-detatch-vcs-roots.png b/images/attach-and-detatch-vcs-roots.png
diff --git a/images/attach-and-detatch-vcs-roots_dark.png b/images/attach-and-detatch-vcs-roots_dark.png
diff --git a/images/build-configuraiton-creation-options.png b/images/build-configuraiton-creation-options.png
diff --git a/images/build-configuraiton-creation-options_dark.png b/images/build-configuraiton-creation-options_dark.png
diff --git a/images/connection-repo-list.png b/images/connection-repo-list.png
diff --git a/images/connection-repo-list_dark.png b/images/connection-repo-list_dark.png
diff --git a/images/create-page-new-design.png b/images/create-page-new-design.png
diff --git a/images/create-page-new-design_dark.png b/images/create-page-new-design_dark.png
diff --git a/images/edit-used-vcs-root-prompt.png b/images/edit-used-vcs-root-prompt.png
diff --git a/images/edit-used-vcs-root-prompt_dark.png b/images/edit-used-vcs-root-prompt_dark.png
diff --git a/images/get-started-new-project.png b/images/get-started-new-project.png
diff --git a/images/get-started-new-project_dark.png b/images/get-started-new-project_dark.png
diff --git a/images/getting-started-auth-settings.png b/images/getting-started-auth-settings.png
diff --git a/images/getting-started-auth-settings_dark.png b/images/getting-started-auth-settings_dark.png
diff --git a/images/import-project-dsl-new-root.png b/images/import-project-dsl-new-root.png
diff --git a/images/import-project-dsl-new-root_dark.png b/images/import-project-dsl-new-root_dark.png
diff --git a/images/new-github-app-redesigned-flow.png b/images/new-github-app-redesigned-flow.png
diff --git a/images/new-github-app-redesigned-flow_dark.png b/images/new-github-app-redesigned-flow_dark.png
diff --git a/images/repo-list-from-connection.png b/images/repo-list-from-connection.png
diff --git a/images/repo-list-from-connection_dark.png b/images/repo-list-from-connection_dark.png
diff --git a/topics/configure-and-run-your-first-build.md b/topics/configure-and-run-your-first-build.md
@@ -200,34 +200,68 @@ You can watch a quick video guide or read the full tutorial below.
 
 ## Create your first 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.
+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.
 
 >__Sample Repository__  
->To try out the setup flow with a sample project, you can use this [GitHub repository](https://github.com/JetBrains/Maven-Configuration-TeamCity-Samples).  
->Or, you can configure the first build based on your own project's sources. In this case, if TeamCity autodetects any build steps in it, we recommend that you read about [their available settings](configuring-build-steps.md) before running the build.
+>To explore the setup flow, you can use [this sample GitHub repository](https://github.com/JetBrains/Maven-Configuration-TeamCity-Samples).
 >
 {style="note"}
 
-Every TeamCity installation has the default __Root__ project that will contain all the other projects you create. The first project you create will be added as a child of the __Root__ project. To add your first project:
-
-1. Click __Administration__ in the upper right corner of the TeamCity UI and then click __Create project__.
-2. 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](guess-settings-from-repository-url.md#VCS+URL+Formats). To use our sample repo, enter:
-   ```Shell
-   https://github.com/JetBrains/Maven-Configuration-TeamCity-Samples
-   ```
-   If access to your repository is restricted, enter the credentials as well.
-   <img src="CreateProject1.png" dark-src="CreateProject1_dark.png" alt="Create a project from a repository URL, Step 1" width="706" border-effect="line" style="block"/>
-3. 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.
-   <img src="CreateProject2.png" alt="" width="706" border-effect="line" style="block"/>
-4. Click __Proceed__.   
-   TeamCity will scan your VCS repository and autodetect the [build steps](configuring-build-steps.md).
-5. Check the boxes of the suitable steps, and they will be added to the first build configuration of this project.
-   <img src="CreateProject3.png" alt="Create a project from a repository URL, Step 3" width="706" border-effect="line" style="block"/>
-
-Congratulations! You are now ready to run the first build based on the just created build configuration. You can go straight to [running it](#Run+your+first+build) and [tweak its settings](#Tweak+your+build+configuration+settings) afterwards.
+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 "**+**".
+
+   <img src="get-started-new-project.png" width="706" alt="Create new project"/>
+
+2. Enter a project name and optional description. You can leave the autogenerated Project ID as is.
+
+    <img src="create-page-new-design.png" width="706" alt="Main create project page"/>
+
+3. A TeamCity project doesn’t perform builds itself — it serves as a container [build configuratons](creating-and-editing-build-configurations.md) and [pipelines](create-and-edit-pipelines.md). Projects only help you organize related builds, manage permissions, and share resources such as [connections](configuring-connections.md) and [build parameters](configuring-build-parameters.md).
+
+   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.
+
+    <img src="build-configuraiton-creation-options.png" width="706" alt="All build config creation options"/>
+
+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](creating-and-editing-build-configurations.md#Use+a+VCS+Root) or selecting a repository via an [authenticated VCS connection](configuring-connections.md).
+
+5. Paste your repository URL. TeamCity supports Git, Subversion, Perforce, Azure, and Mercurial( all supported URL formats are listed [here](guess-settings-from-repository-url.md#VCS+URL+Formats)). For the sample project, use:
+
+    ```Shell
+    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](commit-status-publisher.md)), select a different authentication method. See [Creating and Editing Build Configurations](creating-and-editing-build-configurations.md#Use+a+Repository+URL) for details.
+
+    <img src="getting-started-auth-settings.png" width="706" alt="Auth settings for public repository"/>
+
+6. After you click **Proceed**, TeamCity will locate the repository, check its branches, and prompt you to select the [default one](working-with-feature-branches.md#Default+Branch). 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](maven.md) steps. Select the one that runs `clean test` for the `ch-simple/pom.xml` file and click **Use selected**.
+
+    > Build steps execute sequentially by default, but you can customize their behavior:
+    >
+    > * Disable steps temporarily if they’re not needed.
+    > * Set execution conditions to control when a step runs. For example, only if the previous step fails or depending on the build parameter value (such as [`teamcity.agent.jvm.os.name` parameter](predefined-build-parameters.md) that allows you to run different steps on Linux, Windows, and macOS agents).
+    > * Add bootstrap steps that run before TeamCity checks out sources.
+    >
+    > See the [](configuring-build-steps.md) article for more information on these and other options.
+    > 
+    {style="tip"}
+
+
+Congratulations! You created your first TeamCity project and build configuration. You can now [run the build](#Run+your+first+build) and [tweak configuration settings](#Tweak+your+build+configuration+settings) as needed.
 
 ## Run your first build
+
 To run builds in TeamCity, you need [build agents](install-and-start-teamcity-agents.md). A fresh TeamCity server, installed as described [here](quick-setup-guide.md), has one registered build agent that runs on the same computer. Let's use this agent to run a build on the sample project.
 {instance="tc"}
 
@@ -244,6 +278,7 @@ You will be automatically redirected to the __Build Results__ page, where you ca
 ## Tweak your build configuration settings
 
 You might want to configure the following settings first:
+
 * paths to build [artifacts](#Artifacts)
 * [automatic triggers](#Automatic+Build+Trigger)
 * a custom pattern for a [build number](#Build+Number+Format)

diff --git a/topics/configuring-connections.md b/topics/configuring-connections.md
@@ -1,20 +1,46 @@
 [//]: # (title: Configuring Connections)
 [//]: # (help-id: Configuring Connections)
 
-TeamCity allows storing presets of connections to external services. You can reuse these presets in various places on the server: when creating projects, configuring notifications, integrating with issue trackers, and more. This article gives instructions on how to add each type of connection.
+TeamCity connections store credentials required to access external services. Based on a type of this 3rd-party service, are two major connection categories.
 
-To add a connection, do the following:
+<deflist type="full">
+
+
+<def title="VCS Connections">
+
+These connections store the information needed to access VCS providers such as [](#GitHub), [](#GitLab), [](#Bitbucket+Cloud), and so on. They offer the fastest way to create projects, build configurations, and pipelines — handling authentication automatically so you can simply choose a repository and start configuring your build steps.
+
+<img src="connection-repo-list.png" width="706" alt="Repository list retrieved from a connection"/>
+
+Without a configured connection, you would require to provide credentials for every new pipeline, build configuration, or [root](configuring-vcs-roots.md).
+
+</def>
+
+<def title="Non-VCS Connections">
+
+Connections in this category store information needed to access services other than VCS providers and are used for purposes unrelated to retrieving remote repository sources. For example:
+
+* [Amazon Web Services](#AmazonWebServices) connection allows TeamCity to manage AWS [cloud agents](teamcity-integration-with-cloud-solutions.md) and store build artifacts in [S3 buckets](storing-build-artifacts-in-amazon-s3.md).
+* [Google](#Google) connection is used by the [corresponding authentication module](configuring-authentication-settings.md#Google) to allow users log into TeamCity using their Google accounts.
+* [Slack](#Slack) connection is utilized to set up Slack notifications and [send custom Slack messages from build steps](service-messages.md#Sending+Custom+Slack+Messages).
+* [HashiCorp Vault](hashicorp-vault.md) connection allows you to create remote parameters that retrieve their values from a secrets vault.
+
+
+</def>
+
+</deflist>
+
+To create a new connection, do the following:
 
 1. <include from="common-templates.md" element-id="open-project-settings-tab"><var name="tab-name" value="Connections"/></include>
 2. <include from="common-templates.md" element-id="create-new-connection"/>
 3. Select the connection type, set its _Display name_ to distinguish it from the others, and configure it as described below.
 
-
 <img src="dk-bbconnection-createConnection.png" alt="Create a new TeamCity connection" width="706"/>
 
-If your TeamCity server is [installed behind a proxy](configuring-proxy-server.md), it is important to ensure that this is reflected in the connection settings, if applicable. When configuring a callback URL for a connection, you need to specify all URLs by which the current server can be accessed.  
-After configuring the proxy, remember to also set the new address as the _Server URL_ in __Global Settings__ of TeamCity.
-{instance="tc"}
+You can also create new VCS connections from the **Set up your build** page when adding new configurations or pipelines. Choose the **Connect new repository** option in the drop-down menu to view available options.
+
+<img src="" width="706" alt="Add new VCS connection"/>
 
 ## Azure DevOps
 
@@ -57,7 +83,7 @@ To configure an Azure DevOps OAuth 2.0 connection:
 
 #### Azure DevOps PAT Connection
 
-This type of connection uses personal access tokens. It allows creating a [project from a Git or TFVC repository URL](creating-and-editing-projects.md#From+Repository+URL), creating an [Azure DevOps VCS root](team-foundation-version-control.md), or integrating with the [Azure Board Work Items](azure-board-work-items.md) tracker.
+This type of connection uses personal access tokens. It allows creating a [project from a Git or TFVC repository URL](creating-and-editing-build-configurations.md#Use+a+Repository+URL), creating an [Azure DevOps VCS root](team-foundation-version-control.md), or integrating with the [Azure Board Work Items](azure-board-work-items.md) tracker.
 
 To configure an Azure DevOps PAT connection:
 
@@ -69,7 +95,7 @@ To configure an Azure DevOps PAT connection:
    * the server URL in the `https://{account}.visualstudio.com` format or your Azure DevOps Server as `https://{server}:8080/tfs/`
    * your personal access token
 6. <include from="common-templates.md" element-id="test-and-save-connection"/>
-7. The connection is configured, and now a small Azure DevOps Services icon becomes active in several places where a repository URL can be specified: [create project from URL](creating-and-editing-projects.md#From+Repository+URL), [create VCS root from URL](guess-settings-from-repository-url.md), create [Azure DevOps Server](team-foundation-version-control.md) VCS root, create [Azure Board Work Items](azure-board-work-items.md) tracker. Click the icon, log in to Azure DevOps Services and authorize TeamCity. TeamCity will be granted full access to all the resources that are available to you.   
+7. The connection is configured, and now a small Azure DevOps Services icon becomes active in several places where a repository URL can be specified: [create build configuration from URL](creating-and-editing-build-configurations.md#Use+a+Repository+URL), [create VCS root from URL](guess-settings-from-repository-url.md), create [Azure DevOps Server](team-foundation-version-control.md) VCS root, create [Azure Board Work Items](azure-board-work-items.md) tracker. Click the icon, log in to Azure DevOps Services and authorize TeamCity. TeamCity will be granted full access to all the resources that are available to you.   
    When configuring Commit Status Publisher for Git repositories hosted in TFS/VSTS, the personal access token can be filled out automatically if a VSTS project connection is configured.
 
 >It is possible to configure several VSTS connections. In this case, the server URL will be displayed next to the VSTS icon to distinguish the server in use.
@@ -85,7 +111,7 @@ To configure an Azure DevOps PAT connection:
 {instance="tcc"}
 
 A connection to Bitbucket Cloud can be used to:
-* Create a [project from Bitbucket URL](creating-and-editing-projects.md#From+Repository+URL).
+* Create a [project from Bitbucket URL](creating-and-editing-build-configurations.md#Use+a+Repository+URL).
 * Create a [VCS root from URL](guess-settings-from-repository-url.md).
 * Create a [Mercurial VCS root](mercurial.md).
 * Integrate with a [Bitbucket Cloud issue tracker](bitbucket-cloud.md).
@@ -108,7 +134,7 @@ If you configure multiple Bitbucket connections, the server URL will be displaye
 
 Integration with Bitbucket Server and Data Center currently allows you to:
 
-* create a [project and build configuration from Bitbucket URL](creating-and-editing-projects.md#From+Repository+URL)
+* create a [project and build configuration from Bitbucket URL](creating-and-editing-build-configurations.md#Use+a+Repository+URL)
 * create a [VCS root from URL](guess-settings-from-repository-url.md)
 
 To allow TeamCity to access Bitbucket data, you need to create an incoming application link in Bitbucket to grant TeamCity required permissions.
@@ -142,7 +168,7 @@ To allow TeamCity to access Bitbucket data, you need to create an incoming appli
 TeamCity allows you to create connections to both regular **GitHub.com** instances and **GitHub Enterprise**.
 
 A connection to GitHub can be used to:
-* Create a [project from GitHub URL](creating-and-editing-projects.md#From+Repository+URL).
+* Create a [project from GitHub URL](creating-and-editing-build-configurations.md#Use+a+Repository+URL).
 * Create a [VCS root from URL](guess-settings-from-repository-url.md).
 * Create a [Git VCS root](git.md).
 * Integrate with a [GitHub issue tracker](github.md).
@@ -293,7 +319,7 @@ If you enable the <a href="configuring-authentication-settings.md#GitHub">GitHub
 There are two types of GitLab connections: *GitLab.com* for accounts hosted on the [](https://gitlab.com) site, and *GitLab CE/EE* for accounts on a self-hosted GitLab Community Edition (CE) or Enterprise Edition (EE) server.
 
 A connection to GitLab can be used to:
-* Create a [project from GitLab URL](creating-and-editing-projects.md#From+Repository+URL).
+* Create a [project from GitLab URL](creating-and-editing-build-configurations.md#Use+a+Repository+URL).
 * Create a [VCS root from URL](guess-settings-from-repository-url.md).
 * Integrate with a [GitLab issue tracker](gitlab.md).
 * Enable [GitLab.com authentication](configuring-authentication-settings.md#GitLab.com).
@@ -863,7 +889,7 @@ When your Space connection is configured and installed, return to TeamCity and a
 * URL of the Space server
 * Client ID and secret of your Space application
 
-Save the connection and proceed with adding a [Commit Status Publisher](commit-status-publisher.md) or [Pull Requests](pull-requests.md#JetBrains+Space+Merge+Requests) feature, [enabling Space authentication](configuring-authentication-settings.md#JetBrains+Space), or creating a [project](creating-and-editing-projects.md#From+a+Configured+Connection) / [build configuration](creating-and-editing-build-configurations.md#Create+Build+Configurations+in+TeamCity+UI) / [VCS root](configuring-vcs-roots.md).
+Save the connection and proceed with adding a [Commit Status Publisher](commit-status-publisher.md) or [Pull Requests](pull-requests.md#JetBrains+Space+Merge+Requests) feature, [enabling Space authentication](configuring-authentication-settings.md#JetBrains+Space), or creating a [build configuration or pipeline](creating-and-editing-build-configurations.md#Use+a+Repository+URL) / [build configuration](creating-and-editing-build-configurations.md#Create+Build+Configurations+in+TeamCity+UI) / [VCS root](configuring-vcs-roots.md).
 
 
 ## Kubernetes
@@ -943,6 +969,12 @@ Save the connection and proceed with adding an [NPM Registry Connection](nodejs.
 
 This type of connection allows [processing task streams on your Perforce server](perforce-workspace-handling-in-teamcity.md#Workspace+Deletion). In the connection settings, enter the host and user credentials for accessing the Perforce server (the user must have the [admin](https://www.perforce.com/manuals/p4sag/Content/P4SAG/protections.set.html#protections.set.access_levels) permission).
 
+
+## HashiCorp Vault
+
+This connection allows you to set up integration with a secrets vault where TeamCity remote parameters retrieve their values from. See [](hashicorp-vault.md) to learn more.
+
+
  <seealso>
         <category ref="admin-guide">
             <a href="configuring-vcs-roots.md">Configuring VCS Roots</a>