构建扫描中的自定义数据

Calendar
Craig Atkinson
新功能

构建扫描是轻松共享有关构建数据的绝佳方式，但如果您的团队想要将自己的数据添加到这些构建扫描中怎么办？他们可以！除了构建扫描中自动捕获的丰富信息外，您还可以附加自己的自定义数据，以提供更深入的构建洞察。此自定义数据可以采用标签、链接和键值格式的任意自定义值的形式。

通过将自定义数据添加到构建扫描中，您可以轻松找到特定类型的构建，提供指向 GitHub 上适用源代码提交的快速链接，添加有用的 CI 构建信息等等。然后，当您与队友共享单个构建扫描链接时，他们可以快速轻松地访问有关构建的大量信息，使他们更容易诊断构建环境问题、修复测试失败等等。

如果您不熟悉构建扫描，您可以在我们的 关于该主题的介绍性博客文章 中了解它们。您还可以在 构建扫描用户手册 中找到更多详细信息，探索一些示例构建扫描 或 尝试此示例构建扫描项目。

现在让我们来看一些将自定义数据添加到构建扫描中的示例（有关 其他示例，请参阅用户手册）。

标签

让我们从最简单的自定义数据类型开始：标签。标签是为构建扫描添加简单元数据的一种方式。您可以使用标签为构建添加上下文，例如构建是在本地运行还是在 CI 服务器上运行，构建是否有任何本地更改，失败构建的错误类型等。这是一个 示例构建扫描，它将构建标记为具有

  • 在 CI 上运行
  • 来自 master 分支
  • 包含本地代码更改（“脏”）

例如，要附加一个标签来显示构建是在本地运行还是在 CI 服务器上运行，您可以在其构建脚本中添加以下内容

if (System.getenv("CI")) {
    buildScan.tag "CI"
} else {
    buildScan.tag "LOCAL"
}

然后，在查看构建扫描时，标签将显示在项目名称下方

Build scan tag

除了标签之外，您还可以包含构建扫描读者可能觉得有用的链接。例如，您可以包含指向 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

链接在查看构建扫描时显示在顶部部分

Build scan links

自定义值

自定义值可用于使任何信息成为构建扫描的一部分。在 此示例构建扫描 中，您可以看到相应的 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

在查看构建扫描时，自定义值将显示在主页面上

Build scan custom values

命令行

为了让您在将自定义数据传递到构建扫描的方式上拥有更大的灵活性，您还可以通过命令行指定标签、链接和自定义值。例如，您可以快速将临时信息附加到构建扫描，以

  • 帮助调试特定的本地构建失败
  • 标记实验性构建
  • 添加 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 分支运行的所有构建

Build scan serch results

现场演示

有关使用更多示例添加自定义数据的现场演示，请查看 Luke Daley 和 Etienne Studer 最近在 Bay Area Gradle Users 会议上的演讲。视频从构建扫描概述开始，并在 22:30 左右深入探讨了添加自定义数据的详细信息。

将自定义数据添加到构建扫描可以让您拥有强大的功能和灵活性，可以使用标签、链接或其他针对团队特定需求量身定制的数据来增强构建扫描。然后，您将拥有更多信息可供轻松与您的队友在构建扫描中共享，从而减少诊断构建失败的猜测。扫描愉快！

讨论

相关帖子