自定义数据在构建扫描中
引言
构建扫描是轻松共享构建数据的好方法，但如果您的团队想将自己的数据添加到这些构建扫描中，该怎么办？这是可以做到的！除了在构建扫描中自动捕获的丰富信息外，您还可以附加自己的自定义数据，从而提供对构建更深入的洞察。这些自定义数据可以采用标签、链接和键值格式的任意自定义值形式。
通过在构建扫描中添加自定义数据，您可以轻松找到特定类型的构建，提供指向 GitHub 上相应源代码提交的快速链接，添加有用的 CI 构建信息，等等。然后，当您将单个构建扫描链接与队友共享时，他们就可以快速轻松地访问有关您构建的大量信息，从而更容易地诊断构建环境问题、修复测试失败等等。
如果您不熟悉构建扫描，可以在我们关于此主题的介绍性博文中了解相关信息。您还可以找到更多详细信息，请参阅构建扫描用户手册，探索一些示例构建扫描或尝试使用此示例构建扫描项目。
现在，让我们通过一些在构建扫描中添加自定义数据的示例（请参阅用户手册中其他示例）。
标签 #
让我们从最简单的自定义数据类型开始：标签。标签是向构建扫描添加简单元数据的一种方式。您可以使用标签为构建添加上下文，例如构建是在本地还是在 CI 服务器上运行，构建是否有任何本地更改，失败构建的错误类型等。这是一个示例构建扫描，它将构建标记为
- 在 CI 上运行
- 来自 master 分支
- 包含本地代码更改（“脏”）
例如，要在构建扫描中添加一个显示构建是在本地还是在 CI 服务器上运行的标签，您可以在其构建脚本中添加以下内容：
if (System.getenv("CI")) {
buildScan.tag "CI"
} else {
buildScan.tag "LOCAL"
}
然后在查看构建扫描时，该标签会显示在项目名称下方
链接 #
除了标签，您还可以包含构建扫描读者可能会发现有用的链接。例如，您可以包含一个指向 GitHub 上项目源代码的便捷链接，或者指向 Gradle 构建的 CI 结果的链接。这个示例构建扫描展示了这些链接的外观。
假设您的 CI 工具将构建结果 URL 作为环境变量提供。您可以使用以下代码在构建脚本中获取该值并将其添加为自定义链接：
if (System.getenv("CI")) {
buildScan.link "CI build", System.getenv("BUILD_URL")
}
您还可以灵活地添加项目源代码的当前修订版或提交的链接。下面的示例将构建扫描链接到 GitHub 上相应的提交（前提是 Git 命令行工具可用）：
String commitId = 'git rev-parse --verify HEAD'.execute().text.trim()
buildScan.link "Source", "https://github.com/gradle/gradle-build-scan-quickstart/tree/" + commitId
在查看构建扫描时，链接会显示在顶部部分
自定义值 #
自定义值可用于将*任何*信息添加到构建扫描中。在此示例构建扫描中，您可以看到相应的 CI 构建日期、CI 构建编号和 Git 分支名称作为自定义值。这些值在查看构建扫描时或在 Gradle Enterprise 中搜索构建扫描时可用。让我们通过几个示例来说明如何将自定义值添加到您的构建扫描中。
在第一个示例中，我们假设您的 CI 工具通过环境变量将构建信息注入到构建中。然后，您可以在构建脚本中使用以下代码将构建编号和日期添加到构建扫描中：
if (System.getenv("CI")) {
buildScan.value "CI build number", System.getenv("BUILD_NUMBER")
buildScan.value "CI build date", System.getenv("BUILD_DATE")
}
由于我们是从 Gradle 构建脚本内部设置这些自定义值的，因此您可以运行外部命令来捕获有关项目状态的更多信息。例如，您可以通过运行 Git 命令来添加当前 Git 分支，并使用结果设置一个自定义值：
String branchName = 'git rev-parse --abbrev-ref HEAD'.execute().text.trim()
buildScan.value "Git branch", branchName
在查看构建扫描的主页面上显示了自定义值
命令行 #
为了让您更灵活地将自定义数据传递给构建扫描，您还可以通过命令行指定标签、链接和自定义值。例如，您可以快速将临时信息附加到构建扫描中，以便
- 帮助调试特定的本地构建失败
- 标记实验性构建
- 无需修改构建脚本即可添加特定于 CI 的自定义数据
您可以通过指定具有适当名称的系统属性来做到这一点，如下面的示例所示：
$ gradle build -Dscan.tag.EXPERIMENTAL
$ gradle build -Dscan.link.buildUrl=$CI_BUILD_URL
$ gradle build -Dscan.value.buildNumber=$CI_BUILD_NUMBER
第一个添加了一个名为“EXPERIMENTAL”的标签，第二个添加了一个标题为“buildUrl”的链接，第三个添加了一个名为“buildNumber”的自定义值。
基于自定义数据进行搜索 #
在使用本地部署的构建扫描（如 Gradle Enterprise）时，您可以基于自定义数据（如标签和自定义值）搜索构建扫描。例如，您可以使用此屏幕截图所示的术语搜索所有在 CI 上针对 master 分支运行的构建：
实时演示 #
要观看有关添加自定义数据的实时演示以及更多示例，请观看 Luke Daley 和 Etienne Studer 在湾区 Gradle 用户 meetup 上的最新演讲。视频以构建扫描概述开始，并在大约 22:30 处深入探讨添加自定义数据的详细信息。
向构建扫描添加自定义数据，可让您拥有强大的能力和灵活性，通过标签、链接或其他针对您团队特定需求量身定制的数据来增强您的构建扫描。然后，您就可以在构建扫描中轻松地与您的队友共享更多信息，从而减少诊断构建失败时的猜测。祝您扫描愉快！