在版本控制中存储项目设置 | TeamCity On-Premises 文档

主要收获

您可以在远程存储库中以 XML 或 Kotlin 格式存储单个项目的设置。
默认情况下，版本化设置存储在 .teamcity 目录中，该目录位于 VCS 仓库的根目录，其格式与 TeamCity Data Directory 中的格式相同。您可以将此默认路径更改为远程存储库中的任何自定义位置。
项目设置可以保存到与应用程序源代码相同的仓库中，或一个完全独立的仓库。
您可以选择是否可以通过 TeamCity UI 编辑项目（在这种情况下，TeamCity 会将 UI 中的编辑与远程存储的设置同步），或者仅通过修改 VCS 端的设置文件来编辑。
不同的仓库分支可以存储不同的项目设置。
可以通过 HashiCorp Terraform 使用专用 TeamCity Provider存储和管理全局服务器范围设置。

与 VCS 同步设置

默认情况下，项目设置与版本控制系统的同步功能已被禁用。

要启用它，请转到项目设置 | 版本化设置 | 配置。需要" 启用/禁用版本设置"的权限（系统管理员角色的默认权限）。

您可以在此页面上选择以下选项之一：

使用与父项目（默认）相同的设置。
禁用同步。
启用同步。在这种情况下，您也可以定义在构建开始时要使用哪些设置。参见以下详情。

如果启用了同步，它可以在双向或单向模式下工作。

默认模式是双向同步。当 Allow editing project settings via UI 选项被选中时，此模式将被启用。

双向同步的工作原理如下：

在 TeamCity UI 中对项目设置所做的每次管理更改都会提交到版本控制系统。提交更改的作者与进行相关项目编辑的 TeamCity 用户匹配。
如果更改是在 VCS 端应用的（如果编辑的是 Kotlin 或 XML 设置文件），TeamCity 服务器会检测到这些更改并即时修改项目。
在应用新签入的设置之前，TeamCity 会验证这些设置。如果验证失败（例如，当构建配置引用了不存在的 VCS root 或具有重复的 ID），当前项目设置将保持不变，并且会在界面中显示错误。

如果您禁用 Allow editing project settings via UI选项，项目设置在 UI 中将变为只读，并且仅反映在 VCS 端所做的更改。如果您更倾向于将项目设置定义为代码，或者从只读的 VCS 分支加载设置，这将非常方便。

为项目启用同步也会默认启用其所有子项目的 "使用父项目的设置" 选项。 TeamCity 会同步项目设置中的所有更改（包括修改构建配置、模板、 VCS 根等），但不包括 SSH 密钥。要将单个子项目排除在同步之外，请将其切换到同步已禁用模式。

一旦启用设置同步，TeamCity 会将当前项目树和服务器设置提交到远程存储库。如果目标位置已经存储了项目设置，将会弹出警告。此警告允许您选择 TeamCity 是否应：

将 VCS 中的设置覆盖为 TeamCity 服务器上的当前项目设置（仅在启用了双向同步时有效）；或
从版本控制系统中导入设置，将 TeamCity 服务器上的当前项目设置替换为版本控制中的设置。

选择设置位置

TeamCity 项目设置的默认位置是在存储目标项目的同一存储库根目录下的 .teamcity 文件夹里。根据您的工作流程具体情况和业务需求，此默认设置可能并不适合您的团队。

例如，团队在使用 monorepos，独立的微服务和外部库托管在相邻目录中，可能希望设置单独的 TeamCity 项目，将其设置存储在不同的目录中。为每个项目使用自定义设置目录可确保针对同一 monorepo 的项目不会不断覆盖彼此的设置。

另一个您可能想要实现的场景是将 TeamCity 特定文件移离源文件。这种方法掩盖了您 CI/CD 生态系统的具体细节，使其对外部人员不可见。此外，拥有一个专门的 VCS 库来存储整个 TeamCity 服务器的设置（每个项目都有自己的库文件夹来存储其设置）也有助于设置维护和测试。

要实现这些或类似任务，请使用项目设置 VCS 根目录和 VCS 中的设置路径设置。

单独的 VCS Root

项目设置 VCS 根目录选择器允许您选择 TeamCity 应该使用哪个配置 VCS 根目录来获取和提交项目设置。您可以选择此项目直接拥有或其任何父项目拥有的任何根。

因为一个 VCS 根定义了与远程库的连接，选择一个根意味着选择一个应该存储项目设置的库。

如果您使用与检索代码更改和检出源文件相同的根目录，则项目设置将与您的应用程序存储在同一版本库中。每当您想与源文件并排保存 TeamCity settings 时，使用此设置。
使用单独的根目录进行设置同步可以将项目设置移动到单独的存储库。这种方法对具有第三方贡献者的公共存储库有益，因为将 TeamCity 项目设置存储在单独的存储库中可以确保您的项目不会被不受信任的人员修改。您可以将此存储库设置为私有，以进一步隐瞒 CI/CD 设置的内部工作原理。

请注意，项目设置 VCS 根目录组合框不允许您创建新的根目录。您需要导航到项目设置的 VCS 根目录选项卡，并设置所需的根目录，然后才能在版本化设置页面上使用它。

自定义设置路径

VCS 中的设置路径选项允许您手动指定存储项目设置的目录路径。

您可以将默认 .teamcity 值更改为任何自定义路径（例如， .teamcity-settings/accounting ）或句号（.）。后者允许您直接将设置保存到存储库根目录。

为了防止由不明确的设置源引起的意外错误，当同步已经激活时，TeamCity 不允许您更改设置路径。要修改此路径，请禁用同步并保存设置，然后重新启用并指定所需目录。

定义应用于构建的设置

当 TeamCity 需要启动构建时，它可以应用两种可能的设定中的任何一种：

TeamCity 服务器上的当前设置。这些设置包括所有最新更改，这些更改通过 TeamCity UI 或通过提交到 VCS 中的 project settings directory 应用到服务器。
在版本控制系统中存储的自定义设置。这些是从项目设置目录中存储在非默认分支或为构建选择的特定修订中的设置。

选择应用这两种设置中的哪一种的能力，为您提供了以下选项：

在多个分支中拥有不同的设置在项目设置目录中。这意味着您的分支 A 可以拥有参数、步骤、构建功能、工件发布规则和链设置，这些都可能与分支 B 中的设定不同。
开始个人构建，并在项目设置目录中进行更改，这些更改将影响构建行为。
为您的 history builds 添加更多的灵活性。 TeamCity 最初尝试使用与所选更改时刻相对应的设置。否则，将使用当前项目的设置。

要指定构建开始时 TeamCity 应应用哪些设置，请在管理 | <Project> 版本化设置页面上选择所需的选项。

始终使用当前设置 — 所有构建使用 TeamCity 服务器上的当前项目设置。在分支、历史记录和个人构建中的设置更改将被忽略。用户无法使用自定义项目设置运行构建。
默认使用当前设置 — 常规构建使用 TeamCity 服务器上的最新项目设置。用户可以运行从 VCS 导入设置的自定义构建。
使用 VCS 中的设置 — 所有分支构建和历史构建（使用来自 VCS 的设置）从为构建计算的版本化设置修订中加载设置。用户可以在 IDE 中的个人构建中更改配置设置，或者通过自定义构建对话框在 TeamCity 服务器上使用当前项目设置运行构建。

示例：分支特定设置

在您选择的 VCS 中创建并初始化一个空的存储库。在此示例中，使用了 GitHub.com 上的一个仓库。
从此仓库创建一个新的 TeamCity 项目。
在您的构建配置中添加一个 Python 运行器。
import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.python object Build : BuildType({ name = "Build" // ... steps { python { id = "python_runner" command = script { content = """print ("Running a Python script...")""" } } } // ... })
打开项目设置，并导航到 版本化设置选项卡。
选择以下选项：
- 同步已启用：启用
- 项目设置 VCS 根目录：选择您的项目的 VCS 根目录
- 设置格式：Kotlin
- 构建开始时：选择“使用来自 VCS 的设置”
- 应用快照依赖项和版本控制设置中的更改：启用（请参阅应用快照依赖性和版本控制设置中的更改部分）
单击 Apply 保存您的新设置。 TeamCity 将验证您的构建配置的有效性，并将带有您设置的项目设置目录推送到相关的 VCS 仓库。
将 TeamCity 设置从远程仓库复制到本地存储。
git clone <Clone_URL> .
创建一个新的仓库分支。
git checkout -b custom-branch
编辑本地副本 <project settings directory>/settings.kts （默认情况下为 .teamcity/settings.kts ）文件，如下所示：
import jetbrains.buildServer.configs.kotlin.* import jetbrains.buildServer.configs.kotlin.buildSteps.csharpScript object Build : BuildType({ name = "Build" // ... steps { csharpScript { id = "csharpScript" content = """Console.WriteLine("Running a CSharp script...");""" tool = "%\teamcity.tool.TeamCity.csi.DEFAULT%" } } // ... })
将您的新分支推送到远程仓库。
git add * git commit -a -m "Modify custom-branch settings" git push --set-upstream origin custom-branch
TeamCity 应该会很快收集您的新更改。您可以通过单击项目设置页面版本化设置选项卡上的从 VCS 加载项目设置... 手动触发此过程。
如果您已设置默认的触发器，用于在远程仓库发生变化时启动新的构建，则您的新自定义分支的新构建将自动启动。否则，在构建配置页面上选择所需的分支，然后手动运行新的构建。

因此，您的构建配置现在会根据运行的分支执行不同的操作：主分支运行 Python Script ，而自定义分支运行 C# 脚本。您可以尝试在分支设置和运行分支构建中增加更多的差异，以观察 TeamCity 如何处理您 settings.kts 文件的不同版本。

应用快照依赖性和版本控制设置中的更改

如果在项目的版本化设置页面上禁用了相应选项，TeamCity 将忽略对以下内容所做的编辑：

快照依赖项
签出规则
VCS 根

这适用于编辑现有的依赖关系、检出规则和根，以及创建新的依赖关系、检出规则和根。

例如，下面的 Kotlin 示例说明了同一个项目的两个设置版本。

主（默认）分支定义了三个构建配置，它们在单个的 BC0 → BC3 → BC5 构建链中被链接起来。每个配置都会编辑 "output.txt" 文件并将其传递给下一个配置。
自定义分支通过添加两个新的配置项扩展了原始链：BC0 → BC2 → BC3 → BC4 → BC5。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

project {
    buildType(BC0)
    buildType(BC3)
    buildType(BC5)
}

// 1st build configuration
object BC0 : BuildType({
    name = "BC0"
    artifactRules = "output.txt"
    steps {
        script {
            name = "Prepare File"
            id = "Prepare_File"
            scriptContent = """
                rm output.txt
                touch output.txt
            """.trimIndent()
        }
        script {
            name = "WriteLine"
            id = "WriteLine0"
            scriptContent = """echo "Running BC0 config" > output.txt"""
        }
    }
    // ...
})

// 2nd build configuration
object BC3 : BuildType({
    name = "BC3"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine3"
            scriptContent = """echo "Running BC3 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC0) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 3rd build configuration
object BC5 : BuildType({
    name = "BC5"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine5"
            scriptContent = """echo "Running BC5 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC3) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

     

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

project {
    buildType(BC0)
    buildType(BC2)
    buildType(BC3)
    buildType(BC4)
    buildType(BC5)
}

// 1st build config
object BC0 : BuildType({
    name = "BC0"
    artifactRules = "output.txt"
    steps {
        script {
            name = "Prepare File"
            id = "Prepare_File"
            scriptContent = """
                rm output.txt
                touch output.txt
            """.trimIndent()
        }
        script {
            name = "WriteLine"
            id = "WriteLine0"
            scriptContent = """echo "Running BC5 config" > output.txt"""
        }
    }
    // ...
})

// 2nd build config
object BC2 : BuildType({
    name = "BC2"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine2"
            scriptContent = """echo "Running virtual BC2 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC0) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 3rd build config
object BC3 : BuildType({
    name = "BC3"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine3"
            scriptContent = """echo "Running BC3 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC2) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 4th build config
object BC4 : BuildType({
    name = "BC4"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine4"
            scriptContent = """echo "Running virtual BC4 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC3) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

// 5th build config
object BC5 : BuildType({
    name = "BC5"
    artifactRules = "output.txt"
    steps {
        script {
            name = "WriteLine"
            id = "WriteLine5"
            scriptContent = """echo "Running BC5 config" >> output.txt"""
        }
    }
    dependencies {
        dependency(BC4) {
            snapshot { reuseBuilds = ReuseBuilds.NO }
            artifacts { artifactRules = "output.txt" }
        }
    }
    // ...
})

     

如果您禁用应用快照依赖项和版本控制设置中的更改选项并尝试为自定义分支运行构建，将会失败并显示“无法解析工件依赖项”错误。这是因为对快照依赖项所做的编辑被忽视了。从 TeamCity 的角度来看，此设置无效，因为它需要不存在的配置。

前述设置使 TeamCity 能够自动生成缺失的配置并解决更新的依赖关系，这反过来使得可以应用这些自定义分支设置。

存储安全设置

建议将安全数据存储在 VCS 之外。如果启用了双向同步，将密码和 API 令牌存储在 VCS 之外选项可在项目设置 | 版本化设置 | 配置页面上使用。默认情况下，如果首次为项目启用了版本设置，那么此选项将会被启用，而对于已经在 VCS 中存储了它们设置的项目，此选项将被禁用。

如果启用了此选项，TeamCity 将在 XML 配置文件中存储随机生成的 ID，而不是混淆的密码。实际密码存储在磁盘上的 TeamCity 数据目录下，并未纳入版本控制系统的检查中。

管理 Tokens

如果您需要通过 TeamCity UI 以外的方式（例如，通过 Kotlin DSL）向版本化设置中添加密码（或其他安全值），可以生成一个令牌，在设置中替代此密码使用。

在项目设置s 中，从操作下拉菜单中选择为安全值生成令牌。
输入密码并单击生成令牌。
生成的令牌将被存储在服务器上。您现在可以复制并在项目配置文件中使用它来替代密码。
params { password("<parameter_name>", "credentialsJSON:<token>") }
您只能在配置文件中使用令牌来引用安全值。如果您在 TeamCity UI 中将 "credentialsJSON:<token>" 插入为密码参数的值，TeamCity 将不会获取令牌的底层安全值。反而，“credentialsJSON：<token>”字符串本身将被用作实际的密码值。

您还可以在项目版本化设置部分的令牌选项卡上生成新的安全令牌。启用 "将安全值存储在 VCS 外部" 选项的项目可以使用此选项卡。

令牌选项卡允许查看所有项目令牌，包括未使用的令牌。
当项目的安全数据存储在版本控制系统之外时，它可能会与项目分离：例如，如果带有令牌的项目被移动到层次结构中的其他位置，或从 DSL 在新的 TeamCity 服务器上创建。在这种情况下，您可以在此选项卡上指定项目令牌的值，以便项目可以继续使用它们。

此外，如果您有权限编辑的其他项目中有所需的令牌，TeamCity 将自动找到它们。您可以将在这些项目中使用的安全值复制到您当前的项目。

当一个令牌有一个或多个安全值可用时，按钮会出现在此令牌的对面。单击它以查看可用项目并选择一个项目以复制值，然后单击复制确认您的选择。

安全值可以由项目层次结构继承。如果项目中的某项设置（VCS 根，OAuth 连接，云配置文件）需要密码，为此密码生成的令牌可以在此项目及其任何子项目中使用。为了能够使用继承的密码，子项目必须启用版本设置，并在与其父项目相同的 VCS 中存储设置。
或者，您可以添加一个带有安全值的密码参数，并在嵌套项目中使用对该参数的引用。

将安全数据存储在 VCS 中的影响

如果您决定在 VCS 中存储安全设置，建议您仔细考虑以下影响：

如果项目或构建配置的设置在 VCS 中具有已定义的密码字段，则这些值会以加密形式出现在提交到 VCS 的设置中。
- 如果项目设置存储在与源代码相同的存储库中，任何有权访问存储库的人都可以看到这些加密的密码。
- 如果项目设置存储在在专用存储库中与源代码分开中，并且启用了“ 在构建中显示设置更改 ”选项，任何具有“ 查看 VCS 文件内容 ”权限的用户都可以使用更改差异查看器在 TeamCity 界面中查看所有更改。
通过 VCS 以任意方式更改设置，无论在 TeamCity 中配置的构建配置权限如何，都可以触发任何构建配置的构建并获取任何构建配置的设置。
通过提交错误或恶意的设置，用户可能会影响整个服务器的性能或对其他用户的服务器展示。

建议将密码、API 令牌以及其它安全设置存储在 VCS 之外，使用上文所述的相应配置选项。

请注意，SSH 密钥不会存储在 VCS 仓库中。

存储和管理全球服务器设置

将 Kotlin DSL 或 XML 设置存储在 VCS 中，允许您利用配置即代码的方法进行项目和构建配置。您可以指定项目的层级结构，管理各个配置，动态更改步骤设置和参数，等等。

然而，这种方法不允许您管理服务器范围的设置（如用户和用户组设置、清理规则、通知、认证模块、许可证等）。为了自动化您的服务器管理，需要在 HCL 语言格式中定义所需设置，并使用 HashiCorp Terraform 进行管理。要允许 Terraform 与您的 TeamCity 服务器实例通信，请将专用 TeamCity Terraform 提供商添加到您的 Terraform 配置中。

了解详情:

设置格式

要选择设置格式，请单击显示高级选项，位于项目设置 | 版本化设置 | 配置中。

TeamCity 存储项目设置：

在 XML 格式中
在 Kotlin-based DSL 格式中（请参阅专门的页面）

将当前项目设置提交到版本控制系统

如果您想将当前配置提交到 VCS（例如，之前您将配置错误的设置提交到存储库，TeamCity 无法加载它并显示错误和警告），可以在版本化设置 | 配置页面上使用提交当前项目设置选项。

当 TeamCity 将设置提交到 VCS 时，它使用标准的提交信息，注明 TeamCity 用户作为提交者以及设置已更改的项目。通过 TeamCity 提交的每个设置更改都可以添加固定的自定义前缀，这可以通过 teamcity.versionedSettings.commitMessagePrefix 内部属性实现，例如， teamcity.versionedSettings.commitMessagePrefix=TC 变更\n\n。

显示更改

TeamCity 不仅会同步设置，还会自动显示项目设置的更改，就像它对版本控制中的常规更改所做的那样。您可以配置更改以显示在受影响的构建配置中：在项目设置 | 版本化设置 | 配置选项卡上，单击显示高级选项并勾选在构建中显示设置更改框。只有在您将版本化设置存储在未直接附加到当前构建配置的 VCS 根中时，此选项才有效。如果一个 VCS 根被附加到此配置上，它的变化将默认显示，除非配置了特定的构建触发规则。

如果您在单独的 VCS 根目录中存储版本设置，而不是直接附加到您的构建配置的那个，那么当此复选框打开时，将开始显示对这些 VCS 根目录所做的更改。如果 VCS 根已经连接到您的配置，那么它什么也不会做。

默认情况下，VCS 触发器会忽略此类更改。要启用设置提交上的构建触发，按照以下格式添加一个触发规则： +":root=Settings_root_id;:*。

存储项目设置的 VCS 根目录中的所有更改都列在版本化设置 | 更改日志选项卡上。

在 TeamCity 升级后启用版本设置

XML 设置文件的格式会随着 TeamCity 版本的变更而变更，以适应新的功能和改进。通常，格式在错误修正版本中不会改变，而在主要版本中会发生改变。当 TeamCity 服务器进行升级时，TeamCity 服务器上的当前设置会从旧版本格式改变为当前版本格式。

在升级生产服务器之前，用生产数据升级 TeamCity 测试服务器是一种常见的做法。为了避免意外更改用于较旧版本的生产服务器的设置格式，升级 TeamCity 后将禁用版本设置，并显示相应的健康项。系统管理员有权限启用版本化设置（管理 | 服务器健康状况 | 版本化设置已禁用，单击启用）。启用后，将以当前 TeamCity 版本的格式检查已转换的设置是否在版本控制中。请注意，新的设置将被提交到 VCS 根的默认分支；存储在其他分支中的设置将需要手动更新。

常见问题解答

Q. 我可以应用来自不同版本 TeamCity 服务器的设置吗？

A. 不可以，因为与 TeamCity 数据目录一样，设置的格式因 TeamCity 版本而异。

Q. 设置存储在哪里？
A. 您可以手动配置一个目录来存储项目设置。默认目录是 VCS 根配置库根目录中的 .teamcity 目录。在 VCS 根目录中配置的默认分支将与 Git 和 Mercurial 一起使用。您可以创建专用的 VCS 根来更改存储库或分支（如果是 Perforce、Subversion 或 Azure DevOps（前称 TFS），则更改存储库路径）。

Q. 为什么在我更改 UI 中的设置后，构建运行之前会有延迟？
A. 当通过 UI 更改设置时，TeamCity 会等待更改通过提交到 VCS 完成后，才会使用最新更改运行构建。

Q. 更改的作者是谁？
A. 如果通过用户界面更改设置，在 Git 和 Mercurial 中，VCS 中的提交将以实际通过 UI 进行更改的用户的名义执行。对于 Perforce 和 Azure DevOps Server（以前的 TFS），将使用在 VCS 根中指定的用户名称，在 Subversion 中，提交消息也将包含通过 UI 实际进行更改的 TeamCity 用户的用户名。