skip to content

What is a Gradle Build Scan, and how do you publish one from a build?

level: juniorimportance: must knowfreq 62%

answer

  1. --scan flag
  2. shareable web report of one build
  3. settings.gradle Develocity plugin
  4. accept terms once
  5. prints scan URL

basics

~10 s

A Build Scan is a shareable web report of a build's results. You publish one by adding --scan to any Gradle command; Gradle uploads the data and prints a scan URL.

solid answer

~40 s

A **Build Scan** is a persistent, shareable web record of what happened during a single Gradle build — timings, executed tasks, applied plugins, dependencies, console output, and environment. You publish one ad hoc by appending `--scan` to any invocation, e.g. `./gradlew build --scan`. The first time, Gradle prompts you to accept the terms of service; afterward it uploads the data to `scans.gradle.com` (or your Develocity server) and prints a unique URL. For consistent publishing without the flag, apply the `com.gradle.develocity` (formerly `com.gradle.build-scan`) plugin in `settings.gradle(.kts)` and configure it to publish always or on failure. Scans are the primary tool for diagnosing *why* a build was slow or *why* it behaved differently on another machine, because they capture context a local log cannot.

code

bash · 6 lines
bash
# Ad hoc — uploads to the public server, prompts for terms once
./gradlew build --scan

# Output ends with:
# Publishing build scan...
# https://gradle.com/s/abcdef123456

go deeper

for a junior

Know that --scan publishes a shareable web report and prints a URL, and that terms must be accepted once.

for a middle

Explain both publishing paths (flag vs. Develocity plugin in settings), what the scan captures, and why settings is the required location.

for a senior

Discuss publish-on-failure-only policies, pointing scans at a self-hosted Develocity server, and tagging scans for later filtering.

for a principal

Frame scans as the data backbone for org-wide build observability and the migration path from public scans to Develocity.

## What a Build Scan is A **Build Scan** is a deep, persistent, web-hosted snapshot of one Gradle (or Maven) build invocation. Where the console gives you a transient stream of text, a scan is a structured, navigable record you can open later or send to a teammate via a URL. It captures: the full task execution timeline, which tasks ran vs. were `UP-TO-DATE`/`FROM-CACHE`/`SKIPPED`, applied plugins, the resolved dependency graph, the environment (OS, JVM, Gradle version, JVM args), console and deprecation output, and any failures with stack traces. ## Two ways to publish **1. Ad hoc with `--scan`.** Append the flag to any command: ```bash ./gradlew build --scan ``` The first run prompts you to accept the terms of service for the public `scans.gradle.com` server (a one-time, machine-local acceptance). On success Gradle prints a line like `Publishing build scan... https://gradle.com/s/abc123`. **2. Via the Develocity plugin.** For a team you don't want to rely on people remembering the flag. Apply the plugin in **`settings.gradle.kts`** (it must be in settings, not a build script, because it needs to hook the whole build lifecycle): ```kotlin plugins { id("com.gradle.develocity") version "3.x" } develocity { buildScan { termsOfUseUrl = "https://gradle.com/terms-of-service" termsOfUseAgree = "yes" publishing.onlyIf { true } // or { !it.buildResult.failures.isEmpty() } to publish only on failure } } ``` With terms pre-accepted in config, CI can publish non-interactively. ## Why it matters A scan answers questions a local log cannot: *why was this build slower on CI than on my laptop?*, *which task dominated wall-clock time?*, *did the cache miss, and on what input?* Because the data is captured uniformly and shareable, scans turn "works on my machine" debates into a side-by-side URL comparison. The free public server stores scans; **Develocity** is the self-hosted/commercial product that adds history, trends, failure analytics, and a private build cache. ## Naming note The old plugin id was `com.gradle.build-scan` and later `com.gradle.enterprise`; current Gradle 8.x uses `com.gradle.develocity` with a `develocity { buildScan { ... } }` block. The `--scan` flag works without any plugin for the public server.

  • Where must the Develocity/build-scan plugin be applied, and why there?
    In `settings.gradle(.kts)`, not a project build script. The plugin instruments the entire build lifecycle (settings + all projects), which can only be hooked from the settings phase that runs before any project is configured.
  • Does `--scan` require the plugin to be applied?
    No. The `--scan` flag publishes to the public `scans.gradle.com` server even with no plugin. The plugin is what lets you configure consistent/automatic publishing, terms pre-acceptance, custom tags, and a Develocity server URL.

saying these in an interview costs you the question

  • Claiming a Build Scan is just the console log saved to a file — it is structured, navigable build data, not raw text.
  • Trying to apply the scan/Develocity plugin in a project `build.gradle` instead of `settings.gradle`.

context

resolving links…