配置并运行您的第一个构建

TeamCity 主要元素

在配置项目前，先快速了解一下 TeamCity CI/CD 流程包含的核心元素。 这些元素在 项目管理员指南文章中有更详细的说明。

Build step（构建步骤）

TeamCity 中最小的元素，用于封装一个操作（或一系列操作）。 例如：

• ./buildAll.sh 命令用于启动您的自定义构建脚本。

• mvn clean build 命令用于通过 Maven 构建项目。

• 一系列连续的 cURL 命令，用于将您的项目上传到 FTP 服务器。

构建步进有两个关键特性：不可部分执行，并且与相邻步进在同一台机器上运行。

构建配置 / 流水线

构建配置和 流水线是构建步进的父级。 它们的主要目标是管理这些步进应以何种顺序、在哪些机器（构建代理）上运行。

• 流水线提供了更友好的用户体验，并具备 UI/YAML 切换功能。 在流水线中，构建步进被分组到 作业 中，可在不同的构建代理上并行运行。

• 构建配置拥有更高级的自定义选项，但对于新手用户来说配置更具挑战性。 配置会直接拥有构建步进，无需中间实体，并且会在单个构建代理上从头运行至结束。

Project（项目）

TeamCity 项目可以包含其他项目（子项目），以及流水线和构建配置。 项目不会定义任何可执行文件操作，其主要目的是以易于导航的层次结构分类你的构建配置和流水线。

此外，TeamCity 用户还拥有 角色和权限 ，用于指定允许执行的操作。 这些角色和权限以项目为范围，组织管理员可为每个团队配置单独的顶级项目，每位成员仅能访问相关的子项目、配置和流水线。

Build chain（构建链）

一组具有右到左依赖项的构建配置和/或流水线。 例如，如果"Build"和"Test"是两个独立的流水线，你可以配置"Build → Test"链：

• "Build"可独立触发；

• "Test"依赖于"Build"；

• 因为有此依赖项，触发"Test"会自动先运行"Build"。 "Test"只能在"Build"完成后才能开始。

构建链的部分可以归属于一个或多个项目。

步骤 1：创建 pipeline。

1. 复刻 Gradle & Docker Pipeline (TeamCity Samples)仓库。 可以直接配置第一个项目处理该公共仓库，但复刻后会有更多选项。 例如，可创建和构建拉取请求，并将 TeamCity 状态发布到 GitHub。

2. 在新 TeamCity 安装中，你需要首先 创建项目 ，用于存放我们的示例流水线。 可为同一项目添加更多配置和流水线，或者新建项目和子项目，以构建清晰的构建服务器层次结构。

   在 TeamCity 侧边栏点击加号图标添加新项目，然后输入项目名称及可选描述。

   

3. 项目不会直接拥有任何 CI/CD 操作，而是作为构建配置和流水线的 shell。 因此，在完成项目基础设置后，TeamCity 会要求您选择子元素类型。

   点击 管道 图块并打开下拉菜单，查找所有可用于创建流水线的选项。

   

4. 在下拉菜单中，点击 连接新仓库 ，并选择以下任一选项以连接到你的新复刻仓库：

   • 通过直接仓库 URL 创建流水线。 如选择此选项，你需要手动指定认证选项（SSH 密钥、用户名/密码凭据、访问令牌或匿名）。 最终，TeamCity 只会访问该仓库。

   • 点击 GitHub 图标配置持久的 OAuth 或应用连接至 GitHub。 由于此选项涉及在 GitHub 端安装并授权应用程序，所以配置时需多点击几次。 但从长远运行来看，这种方式更有利。 拥有连接 VCS 提供商后，添加新配置和流水线就像从列表选择所需仓库一样简单——连接会自动处理全部认证设置。

     

5. 将所有设置保留为默认状态。 稍后我们会更改其中一些。

   

   • 默认分支 —— TeamCity 认定为 默认分支 的仓库分支。

   • 在新提交的分支上启动新构建 —— 新提交会 自动运行流水线 的分支列表。

   • 拉取请求 —— 允许 TeamCity 在监控主分支正常变更外，还可以 存储库。

   • 将状态发布到仓库 —— 启用后，TeamCity 会将构建状态（已启动、运行中、成功与失败）回传至 GitHub。 这些状态可在主仓库页面上查看。

6. 点击 创建 ，以保存包含流水线的新项目。 现在你可以添加带有构建步进以执行所需操作的作业。

7. 选择作业图块，在 步数 下添加“Gradle”步进。

8. 设置下列步进设置后，点击 保存 完成配置。

   • 步进名称 —— "构建应用"。

   • 任务 ——clean build。

   • JDK —— 选择与您构建代理架构匹配的 JDK 11。

   例如，在 ARM macOS 设备上，应有类似如下结果（将左上角开关从 可视模式 切换为 YAML ，即可视图和编辑 yml 格式设置）：

   jobs: Job1: name: Job 1 steps: - type: gradle name: Build app tasks: clean build jdk-home: '%env.JDK_11_0_ARM64%'

第 2 步：运行首次构建。

现在第一条流水线已准备好，可以运行并确认一切如预期运作。

1. 点击页面右上角的 运行 来构建应用。 可在 Build log（构建日志） 选项卡中跟踪进度。

   

2. 尝试切换 设置 按钮。 可以通过这种方式在当前项目、构建配置或流水线的编辑和视图模式间切换。

3. 在路径导航栏或侧边栏点击你的流水线，转到概览页。 在此即可查看该流水线所有运行记录。

   

   在此页面点击任意构建号，可查看本次运行详情：运行时长、构建日志、测试结果、已发布工件等。

4. 再次尝试运行同一个流水线。 你会发现其瞬间完成，TeamCity 显示“0 秒”持续时间。 这是因为启用了 TeamCity 的优化功能之一 构建重用 ：如果你上次运行成功且远程仓库和作业本身均未变化，TeamCity 会直接“克隆”之前的运行结果用于新一轮运行，并在作业图块上加上“已复用作业”标签。 你可以在 TeamCity 此处展开了解作业优化。

第 3 步：添加测试作业。

流水线可以包含多个作业，既可顺序运行，也可在不同构建代理上并行。 在本步，你将添加两个上游作业，并学习如何处理构建问题。

1. 点击 设置 进入流水线编辑模式，并按如下方式编辑其 YAML 配置：

   jobs: Job1: name: Job 1 steps: - type: gradle name: Build app tasks: clean build jdk-home: '%env.JDK_11_0_ARM64%' dependencies: - Job2 - Job3 Job2: name: Test suite A steps: - type: gradle name: Run test suite A tasks: test jdk-home: '%env.JDK_11_0_ARM64%' working-directory: test1 Job3: name: Test suite B steps: - type: gradle name: Run test suite B working-directory: test2 tasks: test jdk-home: '%env.JDK_11_0_ARM64%' allow-reuse: false

2. 切换到 可视模式 编辑器，花点时间检查您的新流水线配置。

   

   • 选择初始构建作业，展开其 依赖 设置。 两个测试作业均已勾选，表示构建作业依赖于它们。 新作业无依赖项。 因此，构建作业会等待测试作业全部完成，测试作业等级相同，可以在不同构建代理上同时运行。

   • 在任一测试作业中，检查 Gradle 构建步进设置。 不同于构建作业，这些步进设置了自定义 Build Working Directory（构建工作目录）。 这样 gradle test 任务就会在各自目录而不是仓库根目录启动。

3. 保存并运行更新后的流水线。 由于两个新作业都在运行测试，除了 Build log（构建日志） ，也可用运行结果页的 测试 选项卡跟踪结果。

   

   • "Test suite A" 套件中的测试全部成功。

   • "SecondTestCase" 套件中的测试运行结果各异：部分测试通过，部分失败。 因此，整个作业会被标签为失败。

   • 由于 "Test suite B" 套件作业失败，主构建作业未运行即失败。 这是 TeamCity 的默认逻辑：如果工作流下游某阶段未通过，依赖它的上游操作就不会运行。

4. 修复构建问题可能需要一段时间。 为避免影响后续构建，可以 忽略。 被静音的失败不会阻止后续暂存，也不会导致整个工作流被报告为失败。

   在 测试 选项卡中选择失败的测试，并点击 忽略。

   

5. 在 调查 / 忽略 对话框中，指定以下设置：

   • 调查人——将调查分配给某位 TeamCity 用户，让团队成员知道已经有人在处理。

   • 静音范围——允许选择静音的作用域。 目前你的唯一可用选项是“全项目”，因为你只有一个流水线。

   • 取消静音——设置取消静音策略。 默认"修复时自动取消静音"选项表示，你再次打开此对话框并在调查选项里选择"标记为已修复"时，TeamCity 会停止忽略该问题。

6. 如果将调查分配给自己，可在 我的调查 页面快速访问。

   

7. 在 问题 选项卡静音相关构建问题，方式与在 测试 选项卡静音失败测试类似，然后重新运行流水线。 与上一次运行相比，结果应有以下差异：

   

   • 之前的问题仍然存在，但被标记为静音失败，并显示警察图标以表示正在调查。

   • 最终构建作业不再自动失败。

   • TeamCity 会把静音问题摘要添加到作业图块上。

第 4 步：触发器、分支和拉取请求。

1. 修改分叉仓库中的任意文件（例如 README.md）。 片刻之后，流水线将触发新的运行以处理这些更改。 这是因为在流水线设置的 自动运行流水线 部分中开启了“有新更改时”设置。

   

2. 在 自动运行流水线 部分点击加号图标以添加更多触发器条件。 例如，可以安排每周日自动运行夜间流水线。

   

3. 再提交一次更改，但这次以拉取请求方式发送。 这样做也会触发新的运行。 你可以编辑“有新更改时”触发器以禁用该行为。

4. 你可能注意到，每当创建拉取请求时，TeamCity 触发器会触发流水线两次。 这是因为你设置了 TeamCity 监视所有稳定分支（你的更改会先储存在类似 johndoe-patch-1 的分支中，之后才提交到主分支）以及来自 refs/pull/N 分支的拉取请求。

   可以通过编辑流水线 分支规范在 仓库 部分更改该行为。 例如，你可以禁用将全部分支作为基线规则监视，并手动添加需要监视的分支。 下列规则集允许 TeamCity 只监视两个分支，以及在相应开关启用时监视所有 refs/pull/N 分支：

   -:refs/heads/* +:refs/heads/master +:refs/heads/sandbox

   在此配置下，TeamCity 会忽略像 johndoe-patch-N 这样的拉取请求源分支，仅在创建或修改 refs/pull/N 分支时通过触发器触发流水线。