What is a Gradle init script, and what are the different ways Gradle discovers and applies one?
answer
- runs in initialization phase
- delegate is the Gradle object
- --init-script / init.gradle(.kts) / init.d/
- machine-wide, not in the repo
- global repos & credentials
basics
~10 sAn 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 sAn **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# 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.ktsgo deeper
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).
Explain the initialization phase and the Gradle delegate, and articulate the use case (machine-wide, out-of-repo config like mirrors/credentials).
Discuss application order across all sources and when to choose an init script over settings/build scripts or a distribution.
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.