创建和编辑项目

在 TeamCity 中，实际的构建任务由构建配置和流水线执行。然而，它们都必须放置在一个项目中。

本主题说明了创建项目的不同方法。

根项目和设置继承

在开始之前，请注意，每个 TeamCity 服务器都包含一个内置的、不可删除的项目，称为 Root project（根项目）。所有新项目都作为其子项目创建，但它不能直接托管构建配置和流水线。

在 TeamCity 中，子项目继承其父项目的许多设置和实体，例如连接和云代理配置文件。根项目让您可以利用这一概念并定义服务器范围的资源。例如，您可以创建 AWS 云配置文件，以生成可供服务器上所有项目访问的云代理。

您可以通过点击 <Root project> 面包屑项，在编辑模式中导航到根项目设置...

...或者直接转到 <your_server_URL>/admin/editProject.html?projectId=_Root URL。请注意，由于用户权限是基于项目的，只有根项目管理员可以编辑其设置。

在 TeamCity UI 中创建新项目

可以使用相应的侧边栏按钮添加新的 TeamCity 项目。创建按钮位于项目菜单项旁边，允许您添加由根项目直接拥有的顶级项目。

要添加现有项目的子项目，请点击该项目旁边的相同按钮。

对于全新的 TeamCity 安装，仅提供来自存储库 URL 和手动项目创建选项。在配置与 VCS 托管提供商的连接后，您可以获得更多选项。

从存储库 URL

此选项允许您使用 Git、Subversion、Mercurial、TFS 或 Perforce 存储库（仓库）URL 一次性创建一个新项目和一个子构建配置。您可以使用任何 URL 类型：

常规存储库网页链接： https://github.com/Johndoe/my-sample-app
HTTPS 克隆 URL： https://github.com/Johndoe/my-sample-app.git
SSH 克隆 URL： git@github.com:Johndoe/my-sample-app.git

要开始构建远程存储库，请按照以下步骤操作。

在新项目页面上，点击来自存储库 URL 图块。
选择身份验证类型。
密码 / 访问令牌
输入用户名以及密码或个人访问令牌。对于不需要身份验证即可克隆的公共存储库，您可以将这两个字段留空。如果您稍后添加需要更高访问权限的功能（例如， write 权限用于提交状态发布器功能显示构建状态），您可以在那时配置身份验证设置。
SSH key
如果存储库 URL 是 SSH 克隆 URL，则可用。点击上传 SSH 密钥以添加私钥，该私钥将保存在父项目中（父项目设置| SSH 密钥），并在配置其他项目时出现在下拉菜单中。
了解更多： SSH 密钥管理
下一页包含此项目拥有的项目和构建配置的混合设置。
- 父项目 — 使用此菜单更改项目的父项目。
- 项目名称和构建配置名称 — TeamCity 中可见的公共名称。
- 默认分支 — 将成为 TeamCity 中默认分支的完整分支名称（例如， refs/heads/main）。有关更多信息，请参阅以下文章：默认分支。
- 分支规范 — 指定 TeamCity 应跟踪哪些存储库分支的规则集。默认的 refs/heads/* 规则将所有存储库分支添加到监视列表。请参阅以下主题以了解更多信息：使用功能分支。
此页面上显示名称的 VCS 根存储了您输入的大多数设置：身份验证设置、分支规范和默认分支。要编辑它们，请导航到项目设置| VCS 根目录。
- 什么是 VCS 根
- 配置 VCS 根目录
点击继续。在此阶段，您已经创建了一个项目及其子构建配置，现在编辑配置设置。 TeamCity 打开添加构建步骤，以便您可以向配置添加实际功能并开始构建或测试远程存储库。有关构建步骤的更多信息，请参阅本文。

手动

此选项允许您创建一个完全空白的项目。

在新项目页面上，点击手动图块。
为您的新 TeamCity 项目指定初始设置：
- 父项目 — 使用此菜单更改项目的父项目。
- 名称 — 公共项目名称。
- 项目 ID — 成为项目 URL 的一部分，并用于访问此项目的 REST API 调用、Kotlin DSL 设置等。您可以保留默认值，该值由父项目 ID 和此项目的截断名称组装而成。
- 描述 — 可选的项目描述。
点击创建。您将最终得到一个空项目。重复上述步骤以向其添加子项目，或开始添加构建配置和流水线。

从已配置的连接

如果 TeamCity 项目存储了一个配置的连接到 VCS 提供商，它可以使用此连接快速设置所有身份验证设置并检索远程存储库列表。这是创建多个目标存储在同一托管提供商下的存储库的项目的最便捷方式。

首先，您需要一个连接。在本文中，我们将添加一个到 GitHub 的连接，并使用它添加一个目标为 GitHub 托管存储库的项目。有关其他 VCS 提供商连接的更多信息，请参阅配置连接文章。

添加连接

打开父项目设置。如果您希望未来的连接可用于在此服务器上创建的任何项目，请修改根项目设置。否则，请从添加一个手动创建的空白项目开始。
导航到连接选项卡并点击添加连接。
TeamCity 支持两种 GitHub 身份验证方法：OAuth 2.0 和 GitHub 应用。在本教程中，我们将使用一个自动配置的 GitHub 应用，该应用无需自定义，设置时间不到一分钟。要了解这两种连接类型的更多信息，请参阅本文： GitHub 连接。
选择 GitHub 应用作为连接类型并点击创建应用。
TeamCity 将重定向您到 GitHub 以批准该应用，选择其安装位置（个人账户或组织），并可选地限制其存储库访问。您可以随时通过 GitHub 设置 | 开发者设置 | GitHub 应用查看和编辑 TeamCity 配置的应用，或在 GitHub 设置 | 应用页面上卸载它。
安装应用后，您将返回到 TeamCity，所有连接设置（应用 ID、客户端 ID、客户端密钥等）的值将已填充。点击测试连接以验证设置，然后点击保存以完成设置。

一旦连接配置完成，您将在创建项目页面上看到一个新选项。

创建项目

点击来自 GitHub 应用图块。如果您使用的是新连接，TeamCity 将要求您登录。
TeamCity 将显示通过底层连接可访问的存储库列表。使用搜索面板找到所需的存储库，然后点击以继续。
使用 VCS 连接创建项目会处理所有与身份验证相关的设置。您只需完成从存储库 URL 流程的第 3 和第 4 步。
- 父项目 — 使用此菜单更改项目的父项目。
- 项目名称和构建配置名称 — TeamCity 中可见的公共名称。
- 默认分支 — 将成为 TeamCity 中默认分支的完整分支名称（例如， refs/heads/main）。有关更多信息，请参阅以下文章：默认分支。
- 分支规范 — 指定 TeamCity 应跟踪哪些存储库分支的规则集。默认的 refs/heads/* 规则将所有存储库分支添加到监视列表。请参阅以下主题以了解更多信息：使用功能分支。
此页面上显示名称的 VCS 根存储了您输入的大多数设置：身份验证设置、分支规范和默认分支。要编辑它们，请导航到项目设置| VCS 根目录。
- 什么是 VCS 根
- 配置 VCS 根目录
点击继续。在此阶段，您已经创建了一个项目及其子构建配置，现在编辑配置设置。 TeamCity 打开添加构建步骤，以便您可以向配置添加实际功能并开始构建或测试远程存储库。有关构建步骤的更多信息，请参阅本文。

在 Kotlin DSL 中创建新项目

以下 Kotlin 代码创建了一个包含两个子项目的项目。

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"
   }
})

  

请参阅这些文章以获取更多信息：

通过 REST API 创建新项目

以下请求创建了一个由特定父项目拥有的新空 TeamCity 项目。

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"
    }

  

有关更多信息，请参阅以下 REST API 文档文章：创建和删除项目。

管理项目

您可以在项目页面上查看所有可用的项目和子项目，默认按字母顺序列出。管理员可以自定义默认顺序。

当您从列表中选择一个项目时，TeamCity 会显示项目主页页面，您可以在其中预览其嵌套的构建配置和最近的构建结果。要访问项目的设置，请点击右上角的相应切换按钮以切换到编辑模式。

要复制、移动、删除或归档项目，请使用操作菜单，该菜单位于项目设置页面的右上角。

这些选项对 Root 项目来说并不可用。

复制项目

调用项目操作菜单并点击复制项目...。项目可以由项目管理员复制并移动到另一个项目。

一个副本会复制原始项目的所有设置，子项目，构建配置和模板，但是与构建相关的数据不会保留。副本是在没有构建历史和没有统计数据的情况下创建的。

您可以将项目复制到相同或另一个父级中。

在复制时，TeamCity 会自动为副本分配一个新的名称和 ID。也可以手动更改名称和 ID。
选择复制与项目相关的用户、代理和其他设置选项可确保所有设置（如通知规则或代理的兼容性）对于所有受影响的用户和代理与复制的项目和原始项目完全相同。

您也可以选择复制构建配置的构建编号。

移动项目

调用项目操作菜单并点击移动项目...。

在移动项目时，TeamCity 会保留所有的设置，子项目，构建配置/模板，以及相关数据，还有构建历史记录。

归档项目

调用项目操作菜单并点击归档项目...。请参阅以下帮助文章以了解更多关于归档 TeamCity 项目的信息：归档项目。

批量编辑 ID

调用项目操作菜单并点击批量编辑 ID。
当前的项目和构建配置 IDs 已显示。您可以修改或重置所有子项目，VCS 根，构建配置和模板的 ID。点击重新生成以自动获取新 ID 或手动编辑它们。
点击提交。

暂停 / 激活触发器

调用项目操作菜单并点击暂停 / 激活... 以暂时禁用触发器，这些触发器配置在此项目拥有的多个构建配置中。

导出项目

调用项目操作菜单并点击导出项目... 以将项目移动到不同的 TeamCity 服务器。

删除项目

调用项目操作菜单并点击删除项目...。

当您删除一个项目时，TeamCity 将会移除其 .xml 配置文件。删除后，项目将被移动到 \< TeamCity 数据目录 \>/config/_trash/.ProjectID.projectN 目录。在所有与删除的项目相关的数据（构建历史、工件等）在下一次构建历史清理过程中完全删除之前，有一个可配置的超时期限（默认为5天）。

TeamCity 数据目录 /config/_trash/ 目录不会自动清理，如果您确定不再需要已删除的项目，可以手动清空该目录。

最后修改日期： 2025年 9月 3日