skip to content

Init Scripts

Init scripts applied from the command line or ~/.gradle to inject configuration into every build on a machine. Asked in CI contexts, where init scripts are how mirrors, credentials, and telemetry get added without touching the repo.

part ofGradleread it →
on this pageshow

questions

5

What is a Gradle init script, and what are the different ways Gradle discovers and applies one?

level: juniorimportance: must knowfreq 55%

answer

  1. runs in initialization phase
  2. delegate is the Gradle object
  3. --init-script / init.gradle(.kts) / init.d/
  4. machine-wide, not in the repo
  5. global repos & credentials

basics

~10 s

An init script runs before the build itself, letting you configure Gradle globally. Gradle applies it from ~/.gradle/init.gradle(.kts), any file in ~/.gradle/init.d/, or via the --init-script command-line flag.

solid answer

~40 s

An **init script** is a Gradle script executed during the *initialization phase*, before any settings or build script runs. Its delegate is the `Gradle` object, so it configures the whole invocation — not a single project. Gradle discovers init scripts from several locations, applied in a defined order: (1) the file passed via `--init-script <path>` (repeatable); (2) `~/.gradle/init.gradle` or `init.gradle.kts`; (3) every `.gradle`/`.gradle.kts` file in `~/.gradle/init.d/`, alphabetically; (4) init scripts bundled in a Gradle distribution's `init.d/`. Because they live in the user/Gradle home rather than the project, init scripts are ideal for machine-wide concerns like corporate repository mirrors, credentials, or build scans — config you do NOT want committed to the project repo.

code

bash · 5 lines
bash
# apply a one-off init script for this invocation only
gradle build --init-script ./ci-init.gradle.kts

# the same thing using the short flag, repeatable
gradle build -I a.init.gradle.kts -I b.init.gradle.kts

go deeper

for a junior

Know that it's a script that runs before the build to configure Gradle globally, and name the standard locations (init.gradle(.kts), init.d/, --init-script).

for a middle

Explain the initialization phase and the Gradle delegate, and articulate the use case (machine-wide, out-of-repo config like mirrors/credentials).

for a senior

Discuss application order across all sources and when to choose an init script over settings/build scripts or a distribution.

for a principal

Frame init scripts as a fleet/CI governance lever — baking org policy into a custom distribution's init.d vs. distributing init scripts to agents.

## What an init script is A Gradle build runs in three phases: **initialization**, **configuration**, and **execution**. An *init script* is the only script type that runs during the **initialization phase**, even before `settings.gradle(.kts)`. It is your hook into the very start of a build invocation. Whereas a build script's delegate is a `Project` and a settings script's delegate is a `Settings`, an **init script's delegate is the `Gradle` object** (`org.gradle.api.invocation.Gradle`). That object represents the whole invocation, so an init script configures Gradle itself rather than one project. ## Where Gradle looks for init scripts Gradle applies init scripts from these sources, in this order: 1. Files passed with `--init-script` (a.k.a. `-I`) on the command line — repeatable, applied in the order given. 2. `USER_HOME/.gradle/init.gradle` or `init.gradle.kts`. 3. Every `.gradle` and `.gradle.kts` file in `USER_HOME/.gradle/init.d/`, in alphabetical order. 4. Every `.gradle`/`.gradle.kts` file in the Gradle distribution's `init.d/` directory (lets you bake org-wide config into a custom distribution). `USER_HOME` here means the Gradle user home, normally `~/.gradle` but overridable with `-g`/`--gradle-user-home` or `GRADLE_USER_HOME`. ## Why use one Init scripts run for *every* build on the machine and live outside the project, so they are perfect for cross-cutting, environment-specific setup that should not be checked into a repo: an internal Maven mirror, repository credentials from the environment, applying a build-scan plugin, or enforcing org policy. Because they are not in version control, different developers/agents can carry different init scripts. ```kotlin // ~/.gradle/init.gradle.kts allprojects { repositories { // force everyone through the corporate mirror maven { url = uri("https://nexus.corp.example/repository/maven-public") } } } ``` ## Key takeaway Init script = initialization-phase script, `Gradle` delegate, discovered from `--init-script`, `~/.gradle/init.gradle(.kts)`, `~/.gradle/init.d/`, and the distribution's `init.d/`.

  • If both ~/.gradle/init.gradle.kts and a file in ~/.gradle/init.d/ exist, are they both applied?
    Yes. They are different sources and Gradle applies all of them; init.d files are applied in alphabetical order. They are additive, not mutually exclusive.
  • Why put a corporate repository mirror in an init script rather than the build script?
    Because the mirror is a machine/environment concern that shouldn't be committed to the project repo, and an init script applies it to every build on that machine uniformly.

  • Saying an init script runs per-project or in the configuration phase — it runs once per invocation in initialization.
  • Claiming its delegate is a Project; it is the Gradle object.

context

open as a page

How does an init script differ from a settings script and a build script, and when would you reach for an init script specifically?

level: middleimportance: must knowfreq 45%

basics

~20 s

Each runs in a different phase with a different delegate: init script (initialization, Gradle object), settings script (initialization, Settings), build script (configuration, Project). Use an init script for machine-/CI-wide config you don't commit to the repo.

open as a page

Inside an init script the delegate is the Gradle object. Which lifecycle hooks does it expose, and how would you use allprojects vs settingsEvaluated?

level: middleimportance: should knowfreq 40%

basics

~10 s

The Gradle delegate exposes lifecycle hooks like settingsEvaluated, projectsLoaded, beforeProject/afterProject, and the allprojects {} shortcut. Use allprojects {} to configure every project; use settingsEvaluated {} to act once the settings are known.

open as a page

How would you use an init script in CI to inject a repository mirror and credentials across all builds without committing secrets to any repo?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Generate or ship an init script on the CI agent (e.g. in ~/.gradle/init.d/ or via --init-script) that adds the mirror under allprojects { repositories {} } and reads credentials from environment variables, never literals. The repo stays secret-free.

open as a page

When multiple init scripts apply at once, in what order does Gradle run them, and why can that ordering matter?

level: seniorimportance: nice to knowfreq 25%

basics

~20 s

Gradle applies init scripts in a fixed order: --init-script files (in command-line order), then ~/.gradle/init.gradle(.kts), then ~/.gradle/init.d/ files alphabetically, then the distribution's init.d/. Order matters when later scripts override repositories or settings set by earlier ones.

open as a page