TeamCity On-Premises 2024.03 Help

配置通用设置

一般构建配置设置

在创建构建配置时，请指定以下设置：

设置

描述

名称

构建配置名称。

构建配置 ID

一个在系统中所有构建配置和模板中唯一的 ID，由构建配置名称自动生成，但也可以手动设置。
确保您为构建配置提供了全局唯一的 id，并用项目 ID 作为前缀。
创建构建配置后，其 ID 可以更改，强烈建议对书签中的网页 UI 链接和使用 ID 调用 REST API 进行相应的更改。

描述

构建配置的可选描述。

构建编号格式

在构建开始时解析并分配给 构建编号 的模式。

构建计数器

指定用于构建编号的计数器。 每次构建都会使构建计数器增加 1。 使用Reset 链接将计数器值恢复为 1。

发布工件

选择何时发布制品：

  • "即使构建失败 "（默认）：如果所有之前的步骤都已完成，无论成功与否，都会在构建的最后一步发布构件。

  • "只有在构建状态成功时 "：如果所有之前的步骤都已成功完成，那么在构建的最后一步发布制品。 TeamCity 在发布构件之前，会在服务器上检查当前的构建状态。

  • "始终，即使已经发出构建停止命令"：为所有构建发布制品，即使是中断的构建也不例外（例如，发出 stop 命令后，或指定的构建失败条件中的超时后）。

这个设置不会影响在 build script 中配置的工件发布。

构件路径

定义构建工件的模式。 在首次构建运行后，您可以浏览代理 checkout directory（签出目录） 以配置 artifacts paths（工件路径）。

构建选项

为此构建配置指定额外选项。

构建编号格式

在 构建编号格式 字段中，您可以指定构建开始时解析并赋值给 构建编号 的模式。

在模式中支持以下替换：

模式

描述

%build.counter%

构建计数器对于每一种构建配置都是唯一的。 它由 TeamCity 维护，并且在每次新建开始时，将解析为下一个整数值。 计数器的当前值可以在 构建计数器 字段中进行编辑。

%build.vcs.number.<VCS_root_name>%

用于构建 VCS 根的修订版本，其名称为 <VCS_root_name>。 阅读更多 关于此属性。

%property.name%

具有相应名称的构建属性的值。 所有的 预定义构建参数 都受支持（包括 仅参考服务器属性）。

虽然并非必需，但我们仍然强烈建议确保构建号码的唯一性。 请在构建号中包含构建计数器，并且不要将构建计数器重置为较小的值。 也可以在您的构建脚本中更改构建编号。 有关详细信息，请参考 Build Script 与 TeamCity 的交互。

构建工件路径

构建工件是由构建生成且存储在 TeamCity 服务器上的文件，可以从 TeamCity 用户界面下载，或用作其他构建的产物依赖。 在构建配置的 General Settings 页面上，您可以为代理上的文件指定模式，这些文件将在构建后上传到服务器。

如果您在代理上有一个完成的构建，您可以使用检出目录浏览器 chechoutdirBrowser.png （它列出了代理上检出目录的内容）并从树中选择工件。 TeamCity 将会把它们的路径放到输入字段中。

Artifact Paths 字段支持相对（相对于构建检出目录）和绝对路径。 建议使用相对路径。 您可以指定精确的文件路径或模式，每行或逗号分隔一个。 模式支持 * 和 ** 通配符（见下文）。 每一行可以是 [+:]源 [=> 目标] 形式，用于包含，和 -:来源 [=> 目标] 形式，用于排除发布为构建工件的文件或目录。 在方括号中的部分是可选的。 规则按照右部分进行分组，并按照出现的顺序进行应用：

+:**/* => target_directory -:directory1 => target_directory

将告诉 TeamCity 发布除 directory1 外的所有文件到 目标目录。

线格式说明：

file_name|directory_name|wildcard [ => target_directory|target_archive ]

请注意，虽然源部分支持绝对路径，但建议使用相对于 构建检出目录 的路径。

  • 文件名 — 发布文件。 名称应相对于 构建检出目录。

  • directory_name — 用于发布指定目录中的所有文件和子目录。 目录名称应该是相对于 build checkout directory 的路径。 文件将会保留目录结构的方式进行发布，在指定的目录下（目录本身将不包含在内）。

  • 通配符 — 用于发布符合 Ant 风格通配符 模式的文件（仅支持 * 和 ** 通配符）。 通配符应代表相对于构建检出目录的路径。 文件将会按照通配符匹配的目录结构进行发布（由 “静态” 文字匹配的目录将不会被创建）。 也就是说，TeamCity 将从模式中的通配符首次出现的位置开始创建目录。

  • 您可以在制品的规格中使用 构建参数。 例如，使用 mylib-%system.build.number%.zip 来引用名称中包含构建号的文件。

可选的部分从 => 符号开始，接着是目标目录的名称，可用于将文件发布到指定的目标目录。 如果省略了目标目录，文件将在构建工件的根目录中发布。 您可以使用 . （点）作为对构建检出目录的引用。
目标路径不能是绝对的。 非相对路径在构建过程中会产生错误。

  • 目标目录 — （可选）是结果构建中的目录，该目录将包含由模式左侧部分确定的文件。

  • target_archive—（可选）TeamCity打包构建工件以创建存档的路径，该路径在模式的左侧确定。 TeamCity 将模式的右部视为 target_archive ，只要其以 受支持的存档扩展名 结尾，即 .zip， .7z， .jar， .tar.gz ，或 .tgz。

符号链接（symlink 或软链接）是一个 Linux 文件，它指向其他文件或目录，并代表它们的绝对或相对路径。 如果您需要发布为构建工件的目录包含符号链接，您可以选择两种可能的模式之一：

  • 发布的档案将符号链接包含为符号链接。 这是默认行为。 您可以明确地使用 teamcity:symbolicLinks 属性来修饰一个工件路径，以强制此行为。

    #teamcity:symbolicLinks=as-is %teamcity.build.checkoutDir%/build=>build.zip

  • 发布的存档包括由符号链接引用的文件和文件夹。 要启用此行为，可以按照以下方式为工件规则添加 teamcity:symbolicLinks 属性。

    #teamcity:symbolicLinks=inline %teamcity.build.checkoutDir%/build=>build.zip

请注意，属性只会影响直接在其下声明的工件发布规则。 例如，在下面的示例中，只有 Archive_A 将包含由符号链接引用的文件和文件夹。 Archive_B 将使用默认行为，并将 symlinks 包含为文件。

#teamcity:symbolicLinks=inline Dir_A=>Archive_A.zip Dir_B=>Archive_B.zip

制品路径示例

  • install.zip — 在构建工件中发布一个名为 install.zip 的文件。

  • dist — 发布 dist 目录的内容。

  • target /*.jar — 在目标目录中发布所有 jar 文件。

  • target/**/*.txt=> docs — 发布在目标目录及其子目录中找到的所有 txt 文件。 文件将在 文档 目录下的构建工件中可用。

  • reports => reports，distrib/idea*.zip — 将报告目录发布为报告，将与 idea*.zip 匹配的文件从 distrib 目录发布到构件的根目录中。

  • 如果需要，可以在 zip 压缩文件中使用相对路径： results\result1\Dir1\Dir2 => archive.zip!results/result1/Dir1。

  • 同一个 target_archive 名称可以多次使用，例如：

    • +:*/*.html => report.zip

    • + :*/*.css => report.zip!/css/

    • -:*/*.txt => report.zip

构建选项

以下选项可用于构建配置：

悬挂构建检测

选择 启用挂起构建检测 选项，以便检测可能的“挂起”构建。 如果构建的运行时间明显超过预估的平均运行时间，并且自从超出预估时间以后，构建没有发送任何消息，那么该构建被视为“挂起”。 为了正确检测挂起的构建，TeamCity需要基于几次构建来估计构建的平均运行时间。 因此，如果您有一个新的构建配置，可能会在运行了几次构建后启用此功能是有意义的，这样 TeamCity 就有足够的信息来估计平均运行时间。

允许触发个人构建

您可以通过取消选中 允许触发个人构建 选项（默认开启）来限制运行 个人构建。

启用状态小部件

此选项使得能够在不需要任何用户身份验证的情况下，检索构建配置中最后一次构建的状态和基本详情。 请注意，这也允许获取构建配置中任何特定构建的状态（然而，构建无法列出，除了构建状态（ 成功/失败/内部错误/已取消 ）之外，没有其他信息可以获取）。

状态可以通过下面描述的HTML状态小部件获取，或者通过单个图标：借助REST API或者通过构建配置首页的操作菜单获取。

HTML 状态小部件

这个功能允许您在公司的网站，wiki，Confluence 或任何其它网页上获取当前项目状态的概况。
当 启用状态小部件 选项被启动后，一个 HTML 代码片段可以被插入到外部网页中，并显示当前的构建配置状态。
如需构建状态图标作为单一镜像，请查看 REST 构建状态图标。

以下构建过程信息由状态部件提供：

  • 最新的构建结果

  • Build number（构建号）

  • 构建状态

  • 链接到最新的构建工件。 状态小部件无需用户登录到 TeamCity。

当功能启用时，您需要在网页源码中包含以下代码片段：

  • 将此代码示例添加到 <head> 部分（或者，将 withCss=true 参数添加到 externalStatus.html）：

    <style type="text/css"> @import "<TeamCity_server_URL>/css/status/externalStatus.css"; </style>

  • 在需要显示构建配置状态的地方插入此代码示例：

    <script type="text/javascript" src="<TeamCity_server_URL>/externalStatus.html?js=1"> </script>

  • 如果您更喜欢使用纯 HTML 而不是 javascript，请省略 js=1 参数，并使用 iframe 替代脚本：

    <iframe src="<TeamCity_server_URL>/externalStatus.html"/>

  • 如果您想在不修改 <head> 部分的情况下包含默认的 CSS 样式，可以添加 withCss=true 参数。
    若要提供有关特定构建配置的最新状态信息，请根据需要在 URL 中多次使用以下参数：

    &buildTypeId=<external build configuration ID>

也可以通过将 &buildTypeId=<外部构建配置 ID> 替换为 &projectId=<外部项目 ID> 来显示所有项目构建配置的状态。 您可以选择这些参数的组合，在您的网页上显示所需的项目和构建配置。

您还可以下载和自定义 externalStatus.css 文件（例如，您可以使用 display: none 禁用某些列；请参阅 externalStatus.css 中的注释）。 然而，在这种情况下，您必须不包含withCss=true参数，而是显式提供 CSS 样式，最好在 <head> 部分提供。

限制同时运行的构建数量

您可以限制所有代理上可以同时运行的构建数量。 这个选项有助于提高为您的构建分配资源的效率，避免发生所有代理都忙于单一项目的构建的情况。

您可以通过相关字段限制构建配置的总构建数量，并为每个分支配置详细的限制：

  • 对于构建配置，输入构建的最大总数。 默认情况下，该数字设为 0，允许无限数量的构建同时运行。

  • 对于每个分支的构建限制，请输入换行分隔的规则列表。 每条规则都必须遵循 分支：编号 模式，其中 分支 是一个 逻辑分支名称 或包含 * 的模式， number 指定了每个匹配该模式的分支中可以同时运行的构建的最大数量。 0 允许在指定分支中进行无限数量的构建。

最后修改日期： 16日 7月 2024年
创建和编辑构建配置 更改构建配置类型