管理项目

项目在 TeamCity 中用于组织构建配置和子项目。 teamcity project 命令组可用于浏览项目、管理 VCS 根、管理参数、处理版本化设置的安全令牌，以及导出或验证项目配置。

列出项目

查看全部 TeamCity 项目：

teamcity project list

按父项目筛选：

teamcity project list --parent MyProject

限制结果并以 JSON 格式输出：

teamcity project list --limit 20
teamcity project list --json
teamcity project list --json=id,name,parentProjectId,webUrl

  

项目列表参数

标志	描述
`-p`， `--parent`	按父项目 ID 筛选
`-n`， `--limit`	要显示的项目最大数量
`--json`	输出为 JSON。使用 `--json=` 可列出可用字段， `--json=f1,f2` 可查看指定字段。

项目树

以树形结构显示项目层次，包括子项目和构建配置：

teamcity project tree

显示指定子树：

teamcity project tree MyProject

隐藏构建配置，仅显示项目结构：

teamcity project tree --no-jobs

限制树的深度：

teamcity project tree --depth 2

项目树参数

标志	描述
`--no-jobs`	隐藏构建配置，仅显示项目
`-d`， `--depth`	限制树深度（0 = 不限）

创建项目

在根项目下创建新项目：

teamcity project create MyProject

使用显式 ID 创建：

teamcity project create "My Project" --id MyProject

在父项目下创建：

teamcity project create MyProject --parent ParentProject

以 JSON 格式输出创建的项目（适合脚本使用）：

teamcity project create MyProject --json

项目创建参数

标志	描述
`--id`	显式项目 ID。默认根据名称由 TeamCity 自动生成 ID。
`-p`， `--parent`	父项目 ID。默认为 `_Root`。
`--json`	以 JSON 格式输出
`-w`， `--web`	创建后在浏览器中打开新项目

查看项目详情

查看项目详情：

teamcity project view MyProject

在浏览器中打开项目页面：

teamcity project view MyProject --web

以 JSON 格式输出：

teamcity project view MyProject --json

管理 VCS 根

VCS 根定义了 TeamCity 与版本控制仓库之间的连接。它们是项目级实体，通过继承对子项目可见。

列出 VCS 根

teamcity project vcs list --project MyProject
teamcity project vcs list --project MyProject --json
teamcity project vcs list --project MyProject --plain

   

查看 VCS 根详情

teamcity project vcs view MyProject_GitHubRepo
teamcity project vcs view MyProject_GitHubRepo --json
teamcity project vcs view MyProject_GitHubRepo --web

   

view 命令以可读标签显示所有 VCS 根属性。安全属性（密码、密码短语）将以 ******** 方式隐藏。

创建 VCS 根

使用交互式向导或参数创建 Git VCS 根：

teamcity project vcs create --project MyProject

向导会提示输入仓库 URL、显示名称和认证方法。支持六种认证方法：

# Anonymous (public repos)
teamcity project vcs create --url https://github.com/org/repo.git --auth anonymous

# Password / Personal Access Token
teamcity project vcs create --url https://github.com/org/repo.git \
  --auth password --username oauth2 --password ghp_xxx

# SSH key uploaded to TeamCity
teamcity project vcs create --url git@github.com:org/repo.git \
  --auth ssh-key --ssh-key-name my-deploy-key

# SSH key from the build agent's default key
teamcity project vcs create --url git@github.com:org/repo.git --auth ssh-agent

# SSH key at a custom path on the build agent
teamcity project vcs create --url git@github.com:org/repo.git \
  --auth ssh-file --key-path /path/to/key

# Access token via a project connection
teamcity project vcs create --url https://github.com/org/repo.git \
  --auth token --connection-id PROJECT_EXT_1

   

默认情况下，命令会在创建前测试连接。可使用 --no-test 跳过：

teamcity project vcs create --url https://github.com/org/repo.git --auth anonymous --no-test

   

vcs create 参数

标志	描述
`--url`	存储库 URL
`--name`	显示名称（若未指定则自动从 URL 得出）
`-p`， `--项目`	项目 ID（默认：_Root）
`--auth`	认证方法： `密码`， `ssh-key`， `ssh-agent`， `ssh-file`， `token`， `匿名`
`--username`	用户名（用于密码认证）
`--password`	密码或个人访问令牌
`--stdin`	从标准输入读取密码
`--ssh-key-name`	上传到 TeamCity 的 SSH 密钥名称
`--key-path`	构建代理上 SSH 密钥文件的路径
`--passphrase`	SSH 密钥密码短语
`--connection-id`	OAuth 连接 ID
`--branch`	默认分支（默认： `refs/heads/main`）
`--branch-spec`	分支规范
`--no-test`	创建前跳过连接测试

测试 VCS 根连接

测试现有 VCS 根是否能够连接到仓库：

teamcity project vcs test MyProject_GitHubRepo

删除 VCS 根

teamcity project vcs delete MyProject_GitHubRepo
teamcity project vcs delete MyProject_GitHubRepo --yes  # skip confirmation

管理 SSH 密钥

上传到项目的 SSH 密钥可用于 VCS 根认证（TEAMCITY_SSH_KEY 认证方法）。密钥可被子项目继承。

列出 SSH 密钥

teamcity project ssh list --project MyProject
teamcity project ssh list --project MyProject --json

生成 SSH 密钥对

可在 TeamCity 中直接生成 ed25519 或 RSA 密钥对并显示公钥：

teamcity project ssh generate --name deploy-key --project MyProject
teamcity project ssh generate --name deploy-key --type rsa --project MyProject

将显示的公钥添加到 Git 托管服务为部署密钥。

上传 SSH 密钥

teamcity project ssh upload ~/.ssh/id_ed25519 --project MyProject
teamcity project ssh upload key.pem --name my-deploy-key --project MyProject

删除 SSH 密钥

teamcity project ssh delete my-deploy-key --project MyProject
teamcity project ssh delete my-deploy-key --project MyProject --yes

项目连接

各类连接（OAuth 提供方、Docker 注册、云集成）在项目级配置。这些连接可让 TeamCity 连接外部服务，用于作业而不需在单独作业存储凭据，CLI 可列出、创建、授权和删除它们。

详见配置连接 TeamCity 全参考文档。

列出连接

teamcity project connection list --project MyProject
teamcity project connection list --project MyProject --json

第一列显示连接 ID（如 PROJECT_EXT_42）。该 ID 可被 authorize、 删除 和 vcs create --auth token 使用。

创建 GitHub 应用连接

在项目中注册 GitHub 应用。 GitHub 应用以自身身份认证（无需单独用户令牌），适用于不需要用户上下文 OAuth 的 CI 工作流。

交互式模式下，CLI 通过 GitHub 清单流注册新应用 —— 会打开浏览器，点击创建后凭据会自动返回：

teamcity project connection create github-app -p Backend
teamcity project connection create github-app -p Backend --owner my-org

如已拥有 GitHub 应用，可传递 --no-manifest 并自行提供凭据：

teamcity project connection create github-app -p Backend --no-manifest \
    --name "Backend" --app-id 1234567 --client-id Iv1.abc \
    --private-key-file ./key.pem --stdin <<<"$CLIENT_SECRET"

   

创建后 CLI 会提示运行 authorize ，当前用户将获得绑定应用的令牌。使用 --no-authorize 跳过提示。

创建 Docker 注册表连接

teamcity project connection create docker -p Backend

非交互式场景（CI/CD）可通过标准输入传入密码：

echo "$DOCKER_TOKEN" | teamcity project connection create docker -p Backend \
    --name GHCR --url https://ghcr.io --username my-org --stdin

授权连接

OAuth 类型连接（GitHub 应用、Bitbucket、GitLab 等）需为每个用户单独授权，TeamCity 才能以该用户身份访问上游。例如必须先 vcs create --auth token ，才能通过连接验证仓库。

teamcity project connection authorize PROJECT_EXT_42 -p Backend

命令会通过浏览器完成 OAuth 流程，并将获得的令牌存储到当前用户。没有用户 OAuth 流的连接类型（Docker、AWS）会返回错误。

删除连接

teamcity project connection delete PROJECT_EXT_42 -p Backend
teamcity project connection delete PROJECT_EXT_42 -p Backend --force

传递 --force （或 -f ）可跳过交互式确认提示——便于脚本使用。

管理项目参数

项目参数会被该项目下的所有构建配置继承。其用法与作业参数完全一致。

列出参数

teamcity project param list MyProject
teamcity project param list MyProject --json

获取参数值

teamcity project param get MyProject VERSION

设置参数

teamcity project param set MyProject VERSION "2.0.0"
teamcity project param set MyProject SECRET_KEY "my-secret-value" --secure

删除参数

teamcity project param delete MyProject MY_PARAM

安全令牌

安全令牌允许在版本化设置中引用敏感值（密码、API 密钥），而无需将其存储于版本控制。实际值会安全存储在 TeamCity 中，并通过 credentialsJSON:<token> 标识符引用。

存储安全令牌

存储敏感值并获得一个令牌引用：

# Interactive prompt for the value
teamcity project token put MyProject

# Pass the value directly
teamcity project token put MyProject "my-secret-password"

# Read from stdin (useful for piping)
echo -n "my-secret" | teamcity project token put MyProject --stdin

   

命令会以 credentialsJSON:<uuid> 格式返回令牌。请在版本化设置配置文件中使用该令牌。

检索安全令牌值

检索安全令牌原始值：

teamcity project token get MyProject "credentialsJSON:abc123-def456..."
teamcity project token get MyProject "abc123-def456..."

版本化设置

导出项目设置

将项目设置导出为包含 Kotlin DSL 或 XML 配置的 ZIP 包：

# Export as Kotlin DSL (default)
teamcity project settings export MyProject

# Export as Kotlin DSL explicitly
teamcity project settings export MyProject --kotlin

# Export as XML
teamcity project settings export MyProject --xml

# Save to a specific file
teamcity project settings export MyProject -o settings.zip

# Use relative IDs in the export
teamcity project settings export MyProject --relative-ids

   

导出的归档可用于版本控制 CI/CD 配置、在 TeamCity 实例间迁移设置或以代码形式查看设置。

设置导出参数

标志	描述
`--kotlin`	以 Kotlin DSL 导出（默认）
`--xml`	以 XML 导出
`-o`， `--output`	输出文件路径（默认： `projectSettings.zip`）
`--relative-ids`	导出设置中使用相对 ID（默认启用）

查看版本化设置同步状态

检查某项目版本化设置的同步状态：

teamcity project settings status MyProject
teamcity project settings status MyProject --json

会显示版本化设置是否启用、当前同步状态、上次成功同步时间戳、VCS 根与格式信息，以及上次同步尝试的错误信息。

验证 Kotlin DSL

通过运行 TeamCity 配置生成器验证 Kotlin DSL 配置：

teamcity project settings validate
teamcity project settings validate ./path/to/.teamcity
teamcity project settings validate --verbose

   

命令会自动检测当前目录或其父目录中的 .teamcity 目录。需要 Maven（mvn ），或若 DSL 目录有 Maven 包装器则用包装器（mvnw）。

2026年 8月 6日