skip to content

Init Scripts

4 roadmaps5 questions

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.

on this pageshow

explore

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 these in an interview costs you the question

  • 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

resolving links…

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