Interface BuildScanExtension
-
@NonExtensible public interface BuildScanExtension
The DSL extension for configuring build scans, with the name"buildScan"
.buildScan { // build scan configuration }
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
background(Action<? super BuildScanExtension> action)
Executes the given action in a background thread, allowing the current Gradle work to continue.void
buildFinished(Action<? super BuildResult> action)
Registers a callback that is invoked when the build has finished, but before this extension stops accepting to be called.void
buildScanPublished(Action<? super PublishedBuildScan> action)
Registers a callback that is invoked when a build scan has been published successfully.void
capture(Action<? super BuildScanCaptureSettings> action)
Allows configuring what data will be captured as part of the build scan.boolean
getAllowUntrustedServer()
Whether it is acceptable to communicate with a build scan server with an untrusted SSL certificate.BuildScanCaptureSettings
getCapture()
Allows configuring what data will be captured as part of the build scan.BuildScanDataObfuscation
getObfuscation()
Allows registering functions for obfuscating certain identifying information within build scans.java.lang.String
getServer()
Returns the URL of the Gradle Enterprise server to which the build scans are published.java.lang.String
getTermsOfServiceAgree()
The agreement of the Gradle Terms of Service specified undersetTermsOfServiceUrl(String)
.java.lang.String
getTermsOfServiceUrl()
The location of the Gradle Terms of Service that are agreed to when creating a build scan.boolean
isCaptureTaskInputFiles()
Deprecated.Please useBuildScanCaptureSettings.isTaskInputFiles()
boolean
isUploadInBackground()
void
link(java.lang.String name, java.lang.String url)
Captures a named link for the current build.void
obfuscation(Action<? super BuildScanDataObfuscation> action)
Allows registering functions for obfuscating certain identifying information within build scans.void
publishAlways()
Indicates that a build scan should be published at the end of the build, regardless of whether the build succeeded or failed.void
publishAlwaysIf(boolean condition)
Indicates that, if the given condition is true, a build scan should be published at the end of the build, regardless of whether the build succeeded or failed.void
publishOnFailure()
Indicates that a build scan should be published at the end of the build, if and only if the build failed.void
publishOnFailureIf(boolean condition)
Indicates that, if the given condition is true, a build scan should be published at the end of the build, if and only if the build failed.void
setAllowUntrustedServer(boolean allow)
Specifies whether it is acceptable to communicate with a Gradle Enterprise server using an untrusted SSL certificate.void
setCaptureTaskInputFiles(boolean capture)
Deprecated.void
setServer(java.lang.String server)
Sets the URL of the Gradle Enterprise server to which the build scans are published.void
setTermsOfServiceAgree(java.lang.String agree)
Indicates whether the Gradle Terms of Service specified undersetTermsOfServiceUrl(String)
are agreed to.void
setTermsOfServiceUrl(java.lang.String termsOfServiceUrl)
The location of the Gradle Terms of Service that are agreed to when creating a build scan.void
setUploadInBackground(boolean uploadInBackground)
Specifies whether to upload the build scan in background after the build has finished.void
tag(java.lang.String tag)
Captures a tag for the current build.void
value(java.lang.String name, java.lang.String value)
Captures a named value for the current build.
-
-
-
Method Detail
-
background
void background(Action<? super BuildScanExtension> action)
Executes the given action in a background thread, allowing the current Gradle work to continue.This method is useful for capturing values, tags and links that are expensive to compute. By capturing them in the background, Gradle can continue doing other work, making your build faster.
For example, if you are capturing the Git commit ID as a custom value you should invoke Git in the background:
buildScan.background { def commitId = 'git rev-parse --verify HEAD'.execute().text.trim() value "Git Commit ID", commitId }
All background work will be completed before finishing the build and publishing the build scan.
Any errors that are thrown by the background action will be logged and captured in the build scan.
- Parameters:
action
- the action to execute in the background- Since:
- 1.15
-
tag
void tag(java.lang.String tag)
Captures a tag for the current build. The tag is not required to be unique for a given build.- Parameters:
tag
- the name of the tag, must not be null- Since:
- 1.1
-
value
void value(java.lang.String name, java.lang.String value)
Captures a named value for the current build. The name is not required to be unique for a given build.- Parameters:
name
- the name, must not be nullvalue
- the value, may be null- Since:
- 1.1
-
link
void link(java.lang.String name, java.lang.String url)
Captures a named link for the current build. The name is not required to be unique for a given build.- Parameters:
name
- the name, must not be nullurl
- the url, must not be null- Since:
- 1.1
-
buildFinished
void buildFinished(Action<? super BuildResult> action)
Registers a callback that is invoked when the build has finished, but before this extension stops accepting to be called.- Parameters:
action
- the action to execute when the build has finished- Since:
- 1.2
-
buildScanPublished
void buildScanPublished(Action<? super PublishedBuildScan> action)
Registers a callback that is invoked when a build scan has been published successfully.If
isUploadInBackground()
istrue
, the callback is executed before the build scan is uploaded. If the build scan is accessed immediately, it may not be available yet as it is still being uploaded to the server.- Parameters:
action
- the action to execute when the build scan has been published successfully- Since:
- 1.8
-
setTermsOfServiceUrl
void setTermsOfServiceUrl(java.lang.String termsOfServiceUrl)
The location of the Gradle Terms of Service that are agreed to when creating a build scan.- Parameters:
termsOfServiceUrl
- the location of the Gradle Terms of Service- Since:
- 1.12
-
getTermsOfServiceUrl
java.lang.String getTermsOfServiceUrl()
The location of the Gradle Terms of Service that are agreed to when creating a build scan.- Returns:
- the location of the Gradle Terms of Service
- Since:
- 2.0
-
setTermsOfServiceAgree
void setTermsOfServiceAgree(java.lang.String agree)
Indicates whether the Gradle Terms of Service specified undersetTermsOfServiceUrl(String)
are agreed to.- Parameters:
agree
- true if agreeing to the Gradle Terms of Service, false otherwise- Since:
- 1.12
-
getTermsOfServiceAgree
java.lang.String getTermsOfServiceAgree()
The agreement of the Gradle Terms of Service specified undersetTermsOfServiceUrl(String)
.- Returns:
- the agreement of the Gradle Terms of Service
- Since:
- 2.0
-
setServer
void setServer(java.lang.String server)
Sets the URL of the Gradle Enterprise server to which the build scans are published.- Parameters:
server
- the server URL- Since:
- 1.0
-
getServer
@Nullable java.lang.String getServer()
Returns the URL of the Gradle Enterprise server to which the build scans are published.- Returns:
- null when no enterprise server is configured
- Since:
- 2.0
-
setAllowUntrustedServer
void setAllowUntrustedServer(boolean allow)
Specifies whether it is acceptable to communicate with a Gradle Enterprise server using an untrusted SSL certificate.The default (public) build scan server uses SSL certificates that are trusted by default by standard modern Java environments. If you are using a different build scan server via Gradle Enterprise, it may use an untrusted certificate. This may be due to the use of an internally provisioned or self-signed certificate.
In such a scenario, you can either configure the build JVM environment to trust the certificate, or call this method with
true
to disable verification of the server's identity. Alternatively, you may disable SSL completely for Gradle Enterprise installation but this is not recommended.Allowing communication with untrusted servers keeps data encrypted during transmission, but makes it easy for a man-in-the-middle to impersonate the intended server and capture data.
This value has no effect if a server is specified using the HTTP protocol (i.e. has SSL disabled).
- Parameters:
allow
- whether to allow communication with a HTTPS server with an untrusted certificate- Since:
- 1.1
-
getAllowUntrustedServer
boolean getAllowUntrustedServer()
Whether it is acceptable to communicate with a build scan server with an untrusted SSL certificate.- Returns:
true
it is acceptable to communicate with a build scan server with an untrusted SSL certificate- Since:
- 2.0
-
publishAlways
void publishAlways()
Indicates that a build scan should be published at the end of the build, regardless of whether the build succeeded or failed.- Since:
- 1.1
-
publishAlwaysIf
void publishAlwaysIf(boolean condition)
Indicates that, if the given condition is true, a build scan should be published at the end of the build, regardless of whether the build succeeded or failed.- Parameters:
condition
- whether to publish- Since:
- 1.1
-
publishOnFailure
void publishOnFailure()
Indicates that a build scan should be published at the end of the build, if and only if the build failed.- Since:
- 1.1
-
publishOnFailureIf
void publishOnFailureIf(boolean condition)
Indicates that, if the given condition is true, a build scan should be published at the end of the build, if and only if the build failed.- Parameters:
condition
- whether to publish on failure- Since:
- 1.1
-
setUploadInBackground
void setUploadInBackground(boolean uploadInBackground)
Specifies whether to upload the build scan in background after the build has finished.Defaults to
true
.This allows the build to finish sooner, but can be problematic in build environments that terminate as soon as the build is finished as the upload may be terminated before it completes. Background uploading should be disabled for such environments.
This setting can also be set by the
scan.uploadInBackground
system property, which if set takes precedence over any value set by this method and the default.- Parameters:
uploadInBackground
- whether to upload the build scan in background- Since:
- 3.3
-
isUploadInBackground
boolean isUploadInBackground()
- Returns:
- whether to upload build scan in background
- Since:
- 3.3
-
setCaptureTaskInputFiles
@Deprecated void setCaptureTaskInputFiles(boolean capture)
Deprecated.Specifies whether to capture information about each file used as an input to a task.Defaults to
false
.Enabling this feature may increase the size of the build scan data. This requires more time to transmit to the server, and more storage space at the server. Most builds will not incur a noticeable difference when this feature is enabled. Large builds may increase the build scan data by a handful of megabytes. For most builds, the increase will be negligible.
If using Gradle Enterprise with a good connection to the server this capture should be enabled, as it allows comparing task inputs at a file level when comparing builds.
This property may also be set by the
"scan.capture-task-input-files"
system property. If this is set to any value other than"false"
, the capture will be enabled. If this is set to"false"
, the capture will be disabled. If the capture is enabled or disabled via system property, calling this method has no effect. That is, the system property takes precedence over the value set via this method.This method cannot be called after the root project has finished configuring. Doing so will produce a build time error.
- Parameters:
capture
- whether to capture information about each file use as an input to a task- Since:
- 2.1
-
isCaptureTaskInputFiles
@Deprecated boolean isCaptureTaskInputFiles()
Deprecated.Please useBuildScanCaptureSettings.isTaskInputFiles()
- Returns:
- whether information about each file used as an input to a task will be captured
- Since:
- 2.1
-
getObfuscation
BuildScanDataObfuscation getObfuscation()
Allows registering functions for obfuscating certain identifying information within build scans.- Returns:
- the register of obfuscation functions
- Since:
- 2.4.2
-
obfuscation
void obfuscation(Action<? super BuildScanDataObfuscation> action)
Allows registering functions for obfuscating certain identifying information within build scans.- Parameters:
action
- a function to be applied to the register of obfuscation functions- Since:
- 2.4.2
-
getCapture
BuildScanCaptureSettings getCapture()
Allows configuring what data will be captured as part of the build scan.- Returns:
- the capture settings
- Since:
- 3.7
-
capture
void capture(Action<? super BuildScanCaptureSettings> action)
Allows configuring what data will be captured as part of the build scan.- Parameters:
action
- a function to be applied to the capture settings- Since:
- 3.7
-
-