目录
Gradle Enterprise Gradle插件用户手册
附录D：与Gradle Build Tool和Gradle Enterprise的插件兼容性
Gradle Enterprise Gradle插件用户手册
Gradle Enterprise Gradle插件可与Gradle Enterprise和scans.gradle.com集成。
该插件以前曾被命名为“build scan”插件。随着Gradle 6.0和该插件的版本3.0的发布，它已重命名为“Gradle Enterprise”插件。因此，在讨论旧版本时，本文档在提及插件时会使用术语“build scan”。
该插件以前曾被命名为“build scan”插件。随着Gradle 6.0和该插件的版本3.0的发布，它已重命名为“Gradle Enterprise”插件。因此，在讨论旧版本时，本文档在提及插件时会使用术语“build scan”。
1.设定
版本3.1.1是最新版本，并且与所有Gradle 5.x和更高版本兼容。如果使用的是Gradle的早期版本，请参阅Gradle 4.x和更早版本。
本节中的说明描述了为单个Gradle项目应用和配置插件。请参阅集成许多项目，以获取有关集成环境中构建的所有项目的帮助。
1.1.应用插件
1.1.1.Gradle 6.x及更高版本
此版本的Gradle用com.gradle.enterprise作插件ID。该插件必须应用在构建的设置文件中。
Groovy
settings.gradle
plugins {
id "com.gradle.enterprise" version "3.1.1"
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.enterprise").version("3.1.1")
}
插件将gradleEnterprise {} extension添加到用于配置插件的设置脚本，并将buildScan {}extension扩展添加到根项目。均可用于配置插件。
在本文档的其余部分中，配置示例buildScan {}在构建脚本中使用扩展名。在所有情况下，都可以通过在gradleEnterprise {}扩展脚本中放置配置来在设置脚本中指定此配置。
Groovy
settings.gradle
plugins {
id "com.gradle.enterprise" version "3.1.1"
}
gradleEnterprise {
buildScan {
// plugin configuration
}
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.enterprise").version("3.1.1")
}
gradleEnterprise {
buildScan {
// plugin configuration
}
}
1.1.2.Gradle 5.x
此版本的Gradle用com.gradle.build-scan作插件ID。该插件必须应用于构建的根项目。
Groovy
build.gradle
plugins {
id "com.gradle.build-scan" version "3.1.1"
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.build-scan").version("3.1.1")
}
该插件将buildScan {} extension 扩展添加到用于配置插件的根项目中。
1.2.连接到Gradle Enterprise
要连接到Gradle Enterprise实例，必须配置Gradle Enterprise服务器的位置。
Groovy
build.gradle
buildScan {
server = "https://gradle-enterprise.mycompany.com"
}
Kotlin
settings.gradle.kts
buildScan {
server = "https://gradle-enterprise.mycompany.com"
}
1.2.1.允许不受信任的SSL通信
如果您的Gradle Enterprise服务器使用构建的Java运行时不信任的SSL证书，则在未明确允许不信任的服务器的情况下，您将无法发布构建扫描。
为此，将allowUntrustedServer选项设置为true：
Groovy
Disabling SSL certificate checks
buildScan {
allowUntrustedServer = true
}
Kotlin
Disabling SSL certificate checks
buildScan {
allowUntrustedServer = true
}
使用此配置存在安全风险，因为它使第三方更容易拦截您的构建扫描数据。只有在可以为服务器配置受信任的证书之前，才应将其用作短期解决方法。
1.3.连接到scans.gradle.com
如果未指定Gradle Enterprise服务器的位置，则构建扫描将发布到scans.gradle.com。这需要同意服务条款，可以在https://gradle.com/terms-of-service上找到。
您可以通过在构建中添加以下配置来同意服务条款。
Groovy
build.gradle
buildScan {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
}
Kotlin
build.gradle.kts
buildScan {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
}
如果您不同意构建中的服务条款，则在每次尝试发布到scans.gradle.com时都要交互询问您。
注意不要在其他人可能会建立的项目中同意服务条款。
注意不要在其他人可能会建立的项目中同意服务条款。1.4.集成您的CI工具
Gradle plugin for Jenkins突出显示生成生成扫描的任何Gradle构建的构建扫描链接。这使得查看CI构建的构建扫描变得更加容易。
TeamCity的构建扫描插件也可以提供一个醒目的链接到构建扫描的执行建立。
2.控制何时发布构建扫描
应用插件后，构建扫描不会自动发布。下面介绍了可用于控制何时发布构建扫描的选项。
对于Gradle Enterprise用户，建议将构建配置为对每个构建发布构建扫描。这使Gradle Enterprise可以提供有关组织构建的更多见解。
对于Gradle Enterprise用户，建议将构建配置为2.1.按需发布
您可以将--scan参数添加到任何Gradle构建中以发布构建扫描。
$ ./gradlew assemble --scan
如果该构建不适用该插件，则Gradle将自动应用该版本发布时可用的最新版本。
您还可以通过调用buildScanPublishPrevious插件添加的任务来发布最近运行的构建的构建扫描。
$ ./gradlew buildScanPublishPrevious
于任务名称很长，因此值得使用Gradle的缩写命令行符号来执行任务：
$ ./gradlew bSPP
2.2.发布每个版本
为了发布每个构建的构建扫描，可以使用publishAlways()指令：
Groovy
发布每次构建执行的构建扫描
buildScan {
publishAlways()
}
Kotlin
发布每次构建执行的构建扫描
buildScan {
publishAlways()
}
2.3.根据条件发布
为了自动发布某些版本的版本扫描，可以使用以下指令：
表1.根据条件自动发布的选项
| Option | Description |
|---|---|
|
|
如果给定条件为true，则发布构建扫描，无论构建成功还是失败。 |
|
|
仅当构建失败时才发布构建扫描。 |
|
|
仅在条件满足true 且构建失败时才发布构建扫描。 |
例如，如果您只想从CI系统中发布构建扫描（通过具有CI环境变量来识别），则可以执行以下操作：
Groovy
将构建扫描限制为CI构建
buildScan {
publishAlwaysIf(System.getenv("CI"))
}
Kotlin
将构建扫描限制为CI构建
buildScan {
publishAlwaysIf(!System.getenv("CI").isNullOrEmpty())
}
您可以以相同方式使用其他选项。如果要基于一组条件配置几件事，则可以改用if条件：
Groovy
build.gradle
buildScan {
if (System.getenv("CI")) {
publishAlways()
tag "CI"
}
}
Kotlin
build.gradle.kts
buildScan {
if (!System.getenv("CI").isNullOrEmpty()) {
publishAlways()
tag("CI")
}
}
3.与Gradle Enterprise进行身份验证
（插件3.1+，Gradle Enterprise 2019.4+）
可以将Gradle Enterprise安装配置为要求对构建扫描发布进行身份验证。此外，可以将安装配置为仅允许某些用户发布构建扫描。
Gradle Enterprise访问密钥应与密码一样保密。它们用于授权从构建对Gradle Enterprise的访问。
Gradle Enterprise访问密钥应与密码一样保密。它们用于授权从构建对Gradle Enterprise的访问。3.1.自动访问密钥配置
配置构建环境以通过Gradle Enterprise进行身份验证的最简单方法是使用provisionGradleEnterpriseAccessKey任务。
$ ./gradlew provisionGradleEnterpriseAccessKey
执行后，它将打开您的Web浏览器，并要求确认提供新的访问密钥。如果您尚未登录，将要求您首先在浏览器中登录Gradle Enterprise。
确认后，将生成一个新的访问密钥，并将其存储在Gradle用户主目录中的enterprise/keys.properties文件中（~/.gradle默认情况下）。
同一服务器上任何现有的访问密钥都将在文件中替换，但不会在该服务器上吊销以供在其他地方使用。要撤消旧的访问键，请登录Gradle Enterprise并通过页面右上方的用户菜单访问“My settings”。
如果无法在正确的页面上自动打开浏览器，系统将要求您手动打开构建控制台中提供的链接。
如果无法在正确的页面上自动打开浏览器，系统将要求您手动打开构建控制台中提供的链接。3.2.手动访问密钥配置
当不适合自动配置时，也可以为环境手动配置访问密钥。
3.2.1.创建访问密钥
要创建新的访问密钥，请登录Gradle Enterprise并通过页面右上方的用户菜单访问“My settings”。从那里，使用“Access keys”部分来生成访问密钥。
然后应在构建环境中通过文件或环境变量复制和配置访问密钥值。
3.2.2.通过文件
Gradle Enterprise访问密钥存储在Gradle用户主目录内（~/.gradle默认情况下），位于enterprise/keys.properties的Java属性文件中的。属性名称是指服务器的主机名（host name），而值是访问密钥( access key)。
gradle-enterprise.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq
该文件可能包含多个条目。给定主机值的第一个条目将被使用。
3.2.3.通过环境变量
访问密钥也可以通过GRADLE_ENTERPRISE_ACCESS_KEY环境变量指定。这通常更适合CI构建环境。
环境变量的值格式为«server host name»=«access key»。
$ export GRADLE_ENTERPRISE_ACCESS_KEY=gradle-enterprise.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq
$ ./gradlew build
指定服务器主机名是为了防止将访问密钥传输到与预期不同的服务器上。
4.捕获任务输入文件
（插件2.1+，Gradle 5.0+）
构建扫描捕获任务输入的哈希值，以便在比较构建和其他功能时识别输入的更改。默认情况下，将捕获每个任务输入属性的总体哈希值。这使得确定哪些特性改变任务（例如，源或Java编译类路径），但没有哪单个文件改变。为了识别文件更改，必须捕获每个单独的输入文件的路径和内容哈希，可以将其启用。
4.1.何时启用
捕获任务输入文件会在构建结束时增加传输到构建扫描服务器的数据量。如果与构建扫描服务器的网络连接不良，则可能会增加传输所需的时间。此外，它可能还会增加构建扫描服务器的数据存储要求。
该数据当前仅用于构建比较，仅在Gradle Enterprise中可用，而scans.gradle.com则不可用。如果您使用的是scans.gradle.com，则不建议您启用任务输入文件的捕获。
如果您正在使用Gradle Enterprise并利用其构建缓存来加速构建，则强烈建议启用捕获任务输入文件，因为使用构建比较来识别构建之间的哪些文件已更改对诊断意外的构建缓存未命中非常有效。
4.2.如何启用
可以通过buildScan扩展名或系统属性以编程方式启用任务输入文件捕获。
4.2.1.以编程方式
要以编程方式启用，请使用buildScan构建扫描插件添加的扩展名。
Groovy
build.gradle
buildScan {
captureTaskInputFiles = true
}
Kotlin
build.gradle.kts
buildScan {
isCaptureTaskInputFiles = true
}
请参阅API参考。
4.2.2.通过系统属性
要启用而不修改构建脚本，请向构建提供scan.capture-task-input-files系统属性。如果设置了此属性，并且使用以外的其他任何值false（包括无值），则将启用捕获。如果将该属性设置为false，则无论任何编程设置如何，都将禁用捕获。环境设置始终优先于程序设置。
调用构建时可以指定系统属性：
$ ./gradlew build -Dscan.capture-task-input-files
或者，可以使用JAVA_OPTS或GRADLE_OPTS环境变量将其设置为环境的一部分：
$ export GRADLE_OPTS=-Dscan.capture-task-input-files
或者，可以在项目的gradle.properties文件或用户的gradle.properties文件（即~/.gradle/gradle.properties）中设置。
systemProp.scan.capture-task-input-files
有关指定系统属性的更多信息，请参见Gradle用户手册的“构建环境”一章。
5.扩展构建扫描
您可以轻松地以标记，链接和值的形式在构建扫描中包括额外的自定义信息。这是用于捕获和共享对您的构建和开发过程很重要的信息的非常强大的机制。
该信息可以是您喜欢的任何信息。您可以使用标签标记由持续集成工具运行的所有构建CI。您可以捕获构建发布到的环境的名称作为值。您可以在诸如GitHub之类的在线工具中链接到构建的源修订版。可能性是无止境。
您可以看到定制数据如何显示在图2中：
图1.包含不同类型的定制数据的构建扫描
Gradle Enterprise允许列出和搜索系统中所有构建扫描。除了项目名称，结果和其他属性之外，您还可以通过标签和自定义值查找和过滤构建扫描。例如，在图3中，我们将过滤所有带有标签“CI”和git分支名称为“master”的构建扫描：
图2. Gradle Enterprise中构建扫描的过滤列表
5.1.添加标签
标签通常用于指示构建的类型或类别或关键特征。它们在用户界面中突出显示，并迅速通知用户构建的性质。一个版本可以具有零个或多个标签。
可以通过以下tag()方法在构建时添加它们：
Groovy
在构建的构建扫描中添加标签
buildScan {
if (System.getenv("CI")) {
tag "CI"
} else {
tag "Local"
}
tag System.getProperty("os.name")
}
Kotlin
在构建的构建扫描中添加标签
buildScan {
tag(if (System.getenv("CI").isNullOrEmpty()) "Local" else "CI")
tag(System.getProperty("os.name"))
}
如上面的示例所示，标签通常在条件中作为固定字符串应用，或者在运行时从环境中评估。但是，您无需遵循固定的规则，这些只是建议。
添加标签的语法是：
tag(<tag>)
其中<tag>是字符串。
请注意，声明标签的顺序不会影响构建扫描视图。它们以字母顺序显示，所有大写字母标签显示在其余字符之前。
构建扫描插件v1.9.1 +对捕获的标签施加了限制：
最大标签数：50
标签最大长度：200个字符
5.2.添加链接
建筑物很少孤立地居住。项目来源在哪里？是否有该项目的在线文档？在哪里可以找到项目的问题跟踪器？如果存在并且有URL，则可以将其添加到构建扫描中。
可以通过以下link()方法在构建时添加它们：
Groovy
将VCS URL添加到构建的构建扫描
buildScan {
link "VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}"
}
Kotlin
将VCS URL添加到构建的构建扫描
buildScan {
link("VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}")
}
上面的示例演示了如何将链接附加到在线VCS存储库，该链接指向作为系统属性提供的特定分支。
添加链接的语法为：
link(<label>, <URL>)
<label>只是您选择的字符串标识符，这对您来说意味着什么。
您可以在图2中看到自定义链接的效果，该图显示了标签Source如何成为查看构建扫描的任何人都可以跟随的超链接。
构建扫描插件v1.9.1 +对捕获的链接施加了限制：
最大链接数：20
链接标签最大长度：100个字符
链接网址最大长度：1,000个字符
5.3.添加自定义值
没有上下文，有些信息就没有用。“1G”是什么意思？您可能会猜到它代表1 GB，但是那又是什么呢？只有在附加标签“用于构建的最大堆大小”时，它才有意义。例如，这同样适用于git commit ID，可以将其解释为其他一些没有合适标签的校验和。
自定义值是为需要上下文的这些情况设计的。它们是标准的键值对，其中键是您选择的字符串标签，值也是字符串，通常是从构建环境中评估的。
可以通过以下value()方法在构建时添加它们：
Groovy
向构建的构建扫描添加自定义值
buildScan {
value "Build Number", project.buildNumber
}
Kotlin
向构建的构建扫描添加自定义值
buildScan {
value("Build Number", project.buildNumber)
}
上面的示例演示了如何从项目属性读取内部版本号（假设为此设置了内部版本），并将其作为自定义值附加到内部版本扫描中。
添加值的语法为：
value(<key>, <value>)
其中<key>和<value>均为字符串。
与标签一样，您可以在Gradle Enterprise中按自定义值过滤构建扫描。
构建扫描插件v1.9.1 +对捕获的自定义值施加了限制：
最大自定义值计数：1,000
自定义值密钥的最大长度：1,000个字符
自定义值的最大长度值：100,000个字符
5.4.在构建结束时添加数据
（插件1.2+）
如果自定义数据在构建开始时可用，那么到目前为止您看到的示例都可以很好地工作。但是，如果您要附加仅稍后可用的数据该怎么办？例如，如果clean运行了任务，则您可能希望将构建标记为“从干净构建” 。但是您不知道情况是否如此，直到任务执行图准备就绪。
构建扫描插件提供了一个buildFinished()可以在这些情况下使用的钩子。它推迟附加自定义数据，直到构建完成运行为止。例如，假设您想报告输出build目录占用了多少磁盘空间。构建直到完成才知道这一点，因此解决方案是计算磁盘空间并将其附加到buildFinished()挂钩中的自定义值：
Groovy
在构建结束时添加自定义磁盘使用率值
buildScan {
buildFinished {
value "Disk usage (output dir)", buildDir.directorySize().toString()
}
}
Kotlin
在构建结束时添加自定义磁盘使用率值
buildScan {
buildFinished {
value("Disk usage (output dir)", buildDir.walkTopDown().map { it.length() }.sum().toString())
}
}
该buildFinished()操作可以访问构建的其余部分（包括Project实例），因此它可以提取各种信息。它还有权访问一个BuildResult实例，您可以使用该实例确定构建是否失败，如下所示：
Groovy
从中检查构建状态 buildFinished()
import com.gradle.scan.plugin.BuildResult
...
buildScan {
buildFinished { BuildResult result ->
if (result.failure) {
value "Failed with", result.failure.message
}
}
}
Kotlin
从中检查构建状态 buildFinished()
buildScan {
buildFinished {
if (this.failure != null) {
value("Failed with", this.failure.message)
}
}
}
Gradle构建工具的
BuildListener界面也包含一个buildFinished()钩子。但是，您不能使用它来附加自定义数据，因为它触发得太晚了。您可以使用钩子之类project.afterEvaluate()的buildStarted()方法，BuildListener因为它们可以尽早执行。
5.5.添加昂贵的数据
（插件1.15+）
您可能希望添加到构建扫描中的某些数据捕获起来可能很昂贵。例如，捕获Git提交ID可能需要将git命令作为外部进程执行，这很昂贵。为此，可以在不减慢构建速度的情况下使用以下buildScan.background()方法：
Groovy
使用 background()捕捉到的昂贵的定制值
buildScan {
background {
def commitId = "git rev-parse --verify HEAD".execute().text.trim()
value "Git Commit ID", commitId
}
}
Kotlin
使用 background()捕捉到的昂贵的定制值
import java.io.ByteArrayOutputStream
...
buildScan {
background {
val os = ByteArrayOutputStream()
exec {
commandLine("git", "rev-parse", "--verify", "HEAD")
standardOutput = os
}
value("Git Commit ID", os.toString())
}
}
该方法具有将在单独的线程上执行的功能，该功能使Gradle可以继续执行而不必等待昂贵的工作完成。
在完成构建并发布构建扫描之前，将完成所有后台工作。
后台操作引发的任何错误都将被记录并捕获到构建扫描中。
有关更多信息，请参见 buildScan.background() API reference。
5.6.通过系统属性提供自定义数据
（插件1.3+）
到目前为止的示例已经说明了您的构建文件或初始化脚本如何通过环境变量和系统属性从环境中提取信息。构建扫描插件还允许您通过使用特殊命名的系统属性来注入任何形式的自定义数据。这可以帮助您使构建文件中没有太多与环境无关的信息，这些信息可能与大多数构建用户都不相关。
这些系统属性采用以下形式，具体取决于您要注入链接，标记还是自定义值：
-Dscan.tag.<tag>
-Dscan.link.<label>=<URL>
-Dscan.value.<key>=<value>
以下是一些具体示例，这些示例假定已将构建配置为自动发布构建扫描：
$ ./gradlew build -Dscan.tag.CI
$ ./gradlew build -Dscan.link.VCS=https://github.com/myorg/my-super-project/tree/my-new-feature
$ ./gradlew build "-Dscan.value.CI Build Type=QA_Build"
该功能对于持续集成构建特别有用，因为您通常可以轻松配置CI工具以指定构建的系统属性。CI工具通常能够将系统属性注入到内部版本中，并使用来自CI系统的信息（例如内部版本号）进行插值。
$ ./gradlew build "-Dscan.value.buildNumber=$CI_BUILD_NUMBER"
6.捕获构建扫描ID或地址
（插件1.9+）
构建扫描的地址包含在构建末尾的输出中。但是，您可能希望以其他方式记录构建扫描的ID或URL。构建扫描插件允许您注册将接收此信息的回调。成功发布构建扫描后，将调用该回调。
以下示例构建脚本片段显示了此功能，用于维护创建的构建扫描的日志。
Gradle Enterprise提供了搜索特定用户和/或特定主机创建的构建扫描的能力（以及其他搜索条件）。
Gradle Enterprise提供了搜索特定用户和/或特定主机创建的构建扫描的能力（以及其他搜索条件）。Groovy
创建已发布的构建扫描日志
import com.gradle.scan.plugin.PublishedBuildScan
...
buildScan {
buildScanPublished { PublishedBuildScan scan ->
file("scan-journal.log") << "${new Date()} - ${scan.buildScanId} - ${scan.buildScanUri}\n"
}
}
Kotlin
创建已发布的构建扫描日志
import java.util.Date
...
buildScan {
buildScanPublished {
file("scan-journal.log").appendText("${Date()} - ${this.buildScanId} - ${this.buildScanUri}\n")
}
}
请参阅buildScan.buildScanPublished()方法以获取API详细信息。
7.混淆识别数据
（插件2.4.2+）
构建扫描捕获某些标识信息，例如操作系统用户名，主机名和网络地址。通过将混淆功能注册为构建扫描插件配置的一部分，您可以选择对这些数据进行模糊处理，以使其在构建扫描中无法被解密。
以下示例显示为不同的标识数据注册混淆功能。
Groovy/Kotlin
混淆用户名
buildScan {
obfuscation {
username { name -> name.reverse() }
}
}
混淆主机名
buildScan {
obfuscation {
hostname { host -> host.collect { character -> Character.getNumericValue(character as char) }.join("-") }
}
}
混淆IP地址
buildScan {
obfuscation {
ipAddresses { addresses -> addresses.collect { address -> "0.0.0.0"} }
}
}
8.整合许多项目
尽管通常将此插件直接应用于项目，但也可以使用Gradle的init脚本功能来将其应用于轻松地将其应用于许多项目。这通常用于启用环境中所有构建的集成（即CI构建或开发人员的机器）。
初始化脚本可以与Gradle一起使用，方法是在构建时使用以下-I选项指定脚本的路径：
$ ./gradlew build -I path/to/init.gradle
或者可以将它们放置在~/.gradle/init.d目录中以自动应用到非常构建。
8.1.Gradle Enterprise
以下初始化脚本示例使任何Gradle 5.0或更高版本的构建都可以与Gradle Enterprise服务器集成：
Groovy
gradle-enterprise-init.gradle
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
def pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
def isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
def gradleVersion = GradleVersion.current().baseVersion
def atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
def atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!it.pluginManager.hasPlugin("com.gradle.enterprise")) {
it.pluginManager.apply(GradleEnterprisePlugin)
}
configureExtension(it.extensions["gradleEnterprise"].buildScan)
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin)
configureExtension(extensions["buildScan"])
}
}
}
void configureExtension(extension) {
extension.with {
publishAlways()
server = "https://gradle-enterprise.company.com"
// other configuration
}
}
Kotlin
gradle-enterprise-init.gradle.kts
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
val pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
val isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
val gradleVersion = GradleVersion.current().baseVersion
val atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
val atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!pluginManager.hasPlugin("com.gradle.enterprise")) {
pluginManager.apply(GradleEnterprisePlugin::class)
}
extensions["gradleEnterprise"].withGroovyBuilder {
configureExtension(getProperty("buildScan"))
}
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin::class)
configureExtension(extensions["buildScan"])
}
}
}
fun configureExtension(extension: Any) {
extension.withGroovyBuilder {
"publishAlways"()
setProperty("server", "https://gradle-enteprise.company.com")
// other configuration
}
}
8.2.scans.gradle.com
以下初始化脚本示例使任何Gradle 5.0或更高版本的构建都可以与scans.gradle.com集成：
Groovy
scans-init.gradle
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
def pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
def isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
def gradleVersion = GradleVersion.current().baseVersion
def atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
def atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!it.pluginManager.hasPlugin("com.gradle.enterprise")) {
it.pluginManager.apply(GradleEnterprisePlugin)
}
configureExtension(it.extensions["gradleEnterprise"].buildScan)
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin)
configureExtension(extensions["buildScan"])
}
}
}
void configureExtension(extension) {
extension.with {
termsOfServiceUrl = "https://gradle.com/terms-of-service"
termsOfServiceAgree = "yes"
// other configuration
}
}
Kotlin
scans-init.gradle.kts
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion
initscript {
val pluginVersion = "3.1.1"
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
}
}
val isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
val gradleVersion = GradleVersion.current().baseVersion
val atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
val atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")
if (atLeastGradle6) {
settingsEvaluated {
if (!pluginManager.hasPlugin("com.gradle.enterprise")) {
pluginManager.apply(GradleEnterprisePlugin::class)
}
extensions["gradleEnterprise"].withGroovyBuilder {
configureExtension(getProperty("buildScan"))
}
}
} else if (atLeastGradle5) {
rootProject {
pluginManager.apply(BuildScanPlugin::class)
configureExtension(extensions["buildScan"])
}
}
}
fun configureExtension(extension: Any) {
extension.withGroovyBuilder {
setProperty("termsOfServiceUrl", "https://gradle.com/terms-of-service")
setProperty("termsOfServiceAgree", "yes")
// other configuration
}
}
9.升级到Gradle 6
如果您以前在Gradle 5中使用了构建扫描插件2.x，则升级到3.x插件不仅需要更新版本号。插件的ID已更改，现在必须将其应用于构建的设置文件中。
要升级，请首先找到应用2.x插件的位置并删除它。这可能在根目录build.gradle或build.gradle.kts文件中，并且看起来类似于以下内容：
Groovy
build.gradle
plugins {
id "com.gradle.build-scan" version "2.4.2"
}
Kotlin
build.gradle.kts
plugins {
id("com.gradle.build-scan").version("2.4.2")
}
然后，将以下内容添加到构建的settings.gradle或settings.gradle.kts文件中：
Groovy
settings.gradle
plugins {
id "com.gradle.enterprise" version "3.1.1"
}
Kotlin
settings.gradle.kts
plugins {
id("com.gradle.enterprise").version("3.1.1")
}
任何buildScan {}配置都可以保留在原处，或移动到gradleEnterprise {}块内的设置文件中。有关更多信息，请参见上面的Gradle 6.x部分。
Groovy
settings.gradle
gradleEnterprise {
buildScan {
server = "https://gradle-enterprise.company.com"
}
}
Kotlin
settings.gradle.kts
gradleEnterprise {
buildScan {
server = "https://gradle-enterprise.company.com"
}
}
10.Gradle 4.x及更早版本
10.1.Gradle 2.1 - 4.10.2
低于5.0的Gradle版本与最新的插件和功能不兼容。插件1.16是此类构建的最佳可用版本。插件必须以ID应用于构建的根项目com.gradle.build-scan。
Groovy
build.gradle
plugins {
id "com.gradle.build-scan" version "1.16"
}
Kotlin
build.gradle.kts
plugins {
id("com.gradle.build-scan") version "1.16"
}
10.1.Gradle 2.0
Gradle 2.0不支持plugins {}Gradle 2.1中引入的语法。因此，插件必须以不同的方式应用。
Groovy
build.gradle
buildscript {
repositories {
maven { url "https://plugins.gradle.org/m2/" }
}
dependencies {
classpath "com.gradle:build-scan-plugin:1.16"
}
}
apply plugin: "com.gradle.build-scan"
Kotlin
build.gradle.kts
buildscript {
repositories {
maven(url = "https://plugins.gradle.org/m2/")
}
dependencies {
classpath("com.gradle:build-scan-plugin:1.16")
}
}
apply(plugin = "com.gradle.build-scan")
11.故障排除
11.1.主机名解析速度慢
如果在构建期间看到警告，提示解析本地主机名的速度很慢，则可以通过将主机名映射添加到/etc/hosts文件中来解决此问题。
将这些行添加到/etc/hosts文件中，在下面的代码段中将您的计算机名称替换为“mbpro”：
/etc/hosts
127.0.0.1 localhost mbpro.local
::1 localhost mbpro.local
附录A：API参考
请参阅Javadoc。
附录B：捕获的信息
构建扫描插件会在构建运行时捕获信息，并在构建完成后将其传输到服务器。
捕获的大多数信息都可以视为构建数据。这包括构建中项目的名称，任务，插件，依赖项，名称和测试结果以及其他性质的东西。还捕获了一些更一般的环境信息。这包括您的Java版本，操作系统，硬件，国家/地区，时区和其他此类性质。
值得注意的是，没有捕获正在构建的实际源代码和输出工件。但是，编译器发出的错误消息或测试中的错误可能会揭示源代码的某些方面。
清单
下面的列表详细说明了由构建扫描插件捕获并在构建扫描中传输的重要信息。
-
环境
-
建立
-
Gradle命令行和调用选项（例如，请求的任务，开关）
-
构建控制台输出
-
构建失败异常消息和堆栈跟踪
-
建立弃用消息
-
项目名称和结构
-
Gradle Daemon操作数据（例如开始时间，构建计数）
-
构建缓存配置
-
Gradle生命周期回调
-
访问
可以访问服务器的所有用户都可以查看发布到Gradle Enterprise安装的内部版本扫描。Gradle Enterprise提供了一个搜索界面，用于发现和查找单独的构建扫描。
任何人都可以查看发布到scans.gradle.com的构建扫描，并在发布构建扫描时指定了链接。指向各个构建扫描的链接不可发现，无法猜测，但可以共享。
附录C：插件发行历史
3.1.1-2019年12月13日，
当构建扫描发布需要身份验证时，改进了帮助消息
抑制了由于使用工件转换而导致的构建扫描中的过多日志记录，
如果在macOS上本地主机名解析速度较慢，则可以缓解
3.1-2019年11月25日
支持访问密钥配置将
响应的MIME类型从'text / *'更改为'application / *'
在特殊情况下的固定事件排序
3.0-2019年10月16日
更名为Gradle Enterprise插件
与Gradle 6的兼容性
2.4.2-2019年9月10日，
增加了对用户名，主机名和IP地址混淆的支持
2.4.1-2019年8月20日，
更可靠地捕获日志记录输出
以依赖项解析方式处理重叠的ID
更稳定的构建结束处理
2.4-2019年8月8日
添加了对捕获所有依赖项选择原因的
支持添加了对捕获依赖项变体详细信息的
支持添加了对捕获丰富的依赖项版本约束信息的
支持添加了对捕获依赖项平台和约束详细信息的支持
2.3-2019年5月3日
添加了对插件复合构建的
支持添加了对连续构建的
支持添加了对捕获Java编译期间使用的注释处理器的详细信息的支持
2.2.1- 2019年3月1日，更可靠地捕获buildSrc的任务输入文件
2019年2月2.2日至27日，
捕获收集回调的执行
更加紧凑地捕获了弃用跟踪
，任务输入捕获中的总体性能改进
2.1-2018年12月7日
此版本与Java 8和更高版本的
Capture任务输入文件兼容
2.0.2- 2018年11月6日，
此版本与Gradle 5.0兼容，并
删除了已弃用的-Dscan和-Dscan = false系统属性，分别使用--scan和--no-scan
避免经常连接到HTTPS服务器时发生内存泄漏更改构建类路径
2.0.1-2018年10月29日，
此版本发行是为了与Gradle 5.0-rc-1
兼容，但与后续的Gradle 5.0版本不兼容。请改用2.0.2或更高版本。
2.0-2018年10月17日，
此版本发布是为了与Gradle 5.0-milestone-1
兼容，但与后续的Gradle 5.0版本不兼容。请改用2.0.2或更高版本。
1.16-2018年8月21日，
捕获已解决的模块组件的存储库和源存储库
捕获单个生命周期侦听器和代码单元应用程序的属性
捕获Gradle构建脚本编译详细信息
捕获已弃用的使用通知
捕获包含的构建源
1.15.2-2018年8月10日，
修复Kotlin脚本构建缓存
1.15.1- 2018年7月5日，使用buildScan.background（）修复了潜在的类加载器泄漏
1.15- 2018年7月3日
支持在后台捕获昂贵的自定义值/标签/链接
任务buildScanPublishPrevious懒惰地创建
修复了将包含的构建用作插件和主构建时的错误
1.14-2018年6月12日
进一步的性能改进
消除不必要的隐式连续构建扫描抑制
捕获有关生命周期挂钩执行的信息
1.13.4-2018年5月18日
，尤其是在配置期间，改进了构建扫描插件的性能
1.13.3-2018年5月14日
，使用Gradle 4.7中的新连续构建功能修复了不兼容性
1.13.2-2018年5月8日，
当存在--quiet或-q参数存在时不显示构建扫描发布信息，在发布构建扫描时
重试可能的临时网络错误
1.13.1-2018年4月10日
提高插件数据捕获的性能。
1.13-2018年3月28日，
从构建开始就捕获控制台日志。
1.12.1-2018年2月13日
，服务条款被拒绝时修复消息。
1.12-2018年2月12日
捕获合成版本的构建扫描。
捕获原始任务执行时间。
1.11-2017年12月5日
，从构建开始就捕获测试执行，依赖关系解析和项目结构数据。
提高插件数据捕获的性能。
增强Gradle版本兼容性检查。
1.10.3-2017年11月23日，
修复了与Gradle 3.0.0的Android插件不兼容的问题。
1.10.2-2017年11月7日，
修复了与Gradle 4.4的开发版本不兼容的问题。
1.10.1-2017年10月27日，
修复了与Gradle 4.4的开发版本不兼容的问题。
1.10-2017年10月17日，
检测何时由单一用途守护程序运行构建。
捕获执行构建的JVM的默认字符集。
捕获每个项目的构建路径。
1.9.1-2017年10月10日
，如果需要，提示用户接受许可协议。
捕获控制台输出和网络活动，直到接近构建结束。
限制捕获的定制标记，定制链接和定制值的数量和长度。
1.9-2017年8月15日，
捕获任务图计算。
捕获更多细粒度的项目配置。
捕获构建缓存交互，包括工件打包和解包。
2017年6月1.8日-15日
捕获已解决的请求任务。
启用构建缓存后，捕获构建缓存配置。
启用构建缓存后，捕获每个任务的任务输入。
捕获具有最新和从缓存结果的任务的原始构建调用ID。
记录为什么任务不是最新的原因。
捕获GC和堆内存峰值统计信息。
捕获更多的网络下载活动。
在通过buildScan.buildScanPublished（）成功进行构建扫描发布后获得通知。
在安静级别构建扫描插件日志。
1.7.4-2017年5月29日，
修复了与Gradle 4.0的开发版本不兼容的问题。
1.7.3-2017年5月19日，
修复了与Gradle 4.0的开发版本不兼容的问题。
1.7.2-2017年5月17日，
修复了与Gradle 4.0的开发版本不兼容的问题。
1.7.1-2017年5月3日，
修复了与Gradle 4.0的开发版本不兼容的问题。
1.7-2017年4月24日，
当指定不带模式或主机的buildScan“服务器” URL时，修复NPE。
重叠输出被捕获为任务的不可缓存原因。
2017年2月1.6日至10月10日，
捕获任务输出是否可缓存以及它们是否不可缓存的原因。
捕获网络下载活动。
2017年1月1.5日至1月11日，
捕获是否由于没有源而跳过了任务。
捕获任务是否是生命周期任务（即无操作）。
添加“ mailto：”链接作为自定义生成扫描链接。
1.4-2016年12月21日
，执行许多测试时的性能提高。
2016年11月1.3日至15日
通过常规系统属性捕获标签，链接和/或值。
发布较大的依赖图时减小有效负载大小。
2016年10月1.2日至12月12日
，通过buildScan.buildFinished（）捕获标记，链接和/或值。
1.1.1-2016年9月20日，已
解决通过Android Studio为某些项目创建构建扫描的问题。
2016年9月1.1日至17日
捕获用户定义的标签，链接和任意值。
为每个构建或每个失败的构建创建一个构建扫描。
为上一个之前的版本创建一个版本扫描。
使用--offline构建时，将隐式禁用发布构建扫描。
如果显式配置，则通过不受信任的HTTPS连接发布构建扫描。
通过IDE执行构建时，用于创建构建扫描的多个修复程序。
1.0-2016年6月23日
初始版本。
附录D：与Gradle Build Tool和Gradle Enterprise的插件兼容性
可以在此处找到Gradle，Gradle Enterprise和构建扫描插件的版本之间的兼容性。