Lifecycle Hooks and Listeners

The configuration phase is when Gradle reads every project's build script and registers tasks (but doesn't run them). Project evaluation hooks like afterEvaluate run at the tail of this phase, right after a project's script has been read.

Make the service implement AutoCloseable. Gradle calls close() automatically when the build finishes, so you can stop a server or flush a buffer there. You never call close() yourself.

A BuildService is an object Gradle creates lazily and shares across tasks in a build. It holds state (a counter, a connection pool) safely, lives for the whole build, and Gradle closes it at build end.

afterEvaluate registers a callback that runs after a project's build script has finished being evaluated. You use it when your logic depends on values (like extension properties) that are only set later in that script.

buildFinished captures live build objects, so it breaks the configuration cache. The Flow API replaces it: you inject FlowScope and FlowProviders, call scope.always(MyFlowAction::class) with serializable Property inputs, and the action runs at build completion in a cache-safe way.

OperationCompletionListener is registered through the injected BuildEventsListenerRegistry service and receives FinishEvents (including TaskFinishEvent) without holding mutable global state, so it stays compatible with the configuration cache — unlike gradle.addListener.

A TaskExecutionListener gets a callback before each task runs (beforeExecute) and after it finishes (afterExecute). You register it via gradle.addListener(listener) in the build script or a plugin.

Build-completion hooks run once at the end of the whole build, on success or failure — good for build-global teardown/reporting. finalizedBy attaches a finalizer task to a specific task and runs when that task runs — good for per-task cleanup like collecting reports after a test task.

Register a completion hook that runs on the failure path too — legacy gradle.buildFinished { ... } or a config-cache-safe FlowScope.always FlowAction. Put the teardown there so it executes whether tasks pass or fail.

registerIfAbsent registers a named build service if one with that name doesn't already exist, and returns its Provider either way. That makes it idempotent, so multiple plugins can register the same service safely without conflicts.

Use gradle.taskGraph.whenReady { graph -> ... } (or addTaskExecutionGraphListener with graphPopulated). It fires after configuration, once the full task graph is known but before execution starts, so you can inspect which tasks will run.

gradle.beforeProject and gradle.afterProject register callbacks that fire around the evaluation of EVERY project in the build, receiving the project as an argument. afterEvaluate is scoped to the single project that registers it.

Register completion logic in an init script (~/.gradle/init.gradle.kts or distributed via an init plugin) so it applies to every build. Use a FlowAction reading buildWorkResult to report pass/fail to CI or a dashboard, config-cache-safe.

usesService tells Gradle a task depends on that service. It keeps the service alive while the task runs and lets Gradle order/limit access correctly. Without it, parallel cleanup or constraints can misbehave.

Static/global state isn't safe across parallel tasks or worker processes and the configuration cache forbids capturing live build-script objects. A BuildService is a Gradle-managed, build-scoped, shareable holder that works under both.

Implement an OperationCompletionListener whose onFinish handles TaskFinishEvent — each event already carries start and end times, so you record duration per task path. Aggregate in a thread-safe BuildService since tasks run in parallel.

afterEvaluate runs eager configuration logic that often captures live build state. The configuration cache stores the configured graph and skips re-running configuration, so eager hooks become fragile. Prefer lazy Provider/Property wiring that resolves at execution time.

gradle.projectsEvaluated fires once, after EVERY project in the build has been evaluated. Use it when configuration in one project depends on settings declared in another, so you must wait until all build scripts are read.

gradle.addListener takes one object and inspects which listener interfaces it implements — e.g. TaskExecutionListener, TaskExecutionGraphListener, ProjectEvaluationListener, BuildListener — and routes the matching events to it. One object can implement several.