Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Build Scripts: Groovy and Kotlin DSL

Gradle Properties: gradle.properties, -P and Extra Values

Configure builds with gradle.properties, -P and -D flags, environment variables and extra properties, and learn the precedence rules and how to keep secrets out of git.

A build needs settings that do not belong in the script itself: a version number, a feature flag, memory for the daemon, credentials for a private repository. Gradle offers several places to put them. Knowing which one to choose, and which wins when the same name is set twice, saves a lot of debugging. This lesson covers gradle.properties, command-line flags, environment variables and the extra map, plus how to read them safely.

Gradle code is read-only; a runnable Java stand-in demonstrates property precedence.

gradle.properties

A plain key=value file read at startup. It can live in several places:

  • the project root (commit it to git): shared defaults for the team;
  • the Gradle user home (~/.gradle/gradle.properties): personal or machine settings and secrets, never committed.
PROPERTIES
# gradle.properties
group=com.example.shop
version=2.1.0

# Gradle's own settings
org.gradle.jvmargs=-Xmx2g -XX:+HeapDumpOnOutOfMemoryError
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true

# your own properties
featureFlagBeta=false

Names starting with org.gradle. configure Gradle itself. Any other name becomes a project property you can read from build scripts.

Reading project properties

In Kotlin:

Kotlin
val beta = providers.gradleProperty("featureFlagBeta").orElse("false").map(String::toBoolean)
val owner: String by project                    // fails if missing
val optionalOwner = findProperty("owner") as String?   // null if missing

println("beta = ${beta.get()}")

In Groovy:

GROOVY
def beta = providers.gradleProperty('featureFlagBeta').orElse('false')
println "beta = ${beta.get()}"
println project.hasProperty('owner') ? owner : 'no owner'

Prefer providers.gradleProperty(...): it is lazy and works with the configuration cache. Properties named version and group are assigned to the project automatically.

Setting properties on the command line

Terminal
./gradlew build -PfeatureFlagBeta=true         # project property
./gradlew build -Dorg.gradle.parallel=false    # JVM system property for Gradle
./gradlew build -Dorg.gradle.project.version=3.0.0   # system property that sets a project property

Environment variables with the prefix ORG_GRADLE_PROJECT_ also become project properties; this is the usual way to pass secrets on CI:

Terminal
export ORG_GRADLE_PROJECT_repoPassword=s3cret
./gradlew publish

Plain environment variables (such as CI or HOME) are read with providers.environmentVariable("CI") or System.getenv("CI").

Precedence: who wins?

When the same name appears in several places, the more specific source overrides the more general one. As a rule of thumb, from strongest to weakest:

  1. Command line (-P, -D).
  2. Environment variables with the ORG_GRADLE_PROJECT_ prefix.
  3. gradle.properties in the Gradle user home.
  4. gradle.properties in the project root.
  5. Defaults in your build script (orElse).
flowchart LR
  A["Script default<br/>orElse(...)"] --> B["Project gradle.properties"]
  B --> C["User home gradle.properties"]
  C --> D["ORG_GRADLE_PROJECT_ env"]
  D --> E["-P on command line"]

Each step to the right overrides the one before it.

Stand-in: precedence in Java

This program is not Gradle's loader, but it applies the layered lookup so you can experiment with what wins.

Java Stand-in: layered property lookup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that featureFlagBeta is true: the command line overrides the project file. And org.gradle.jvmargs is -Xmx4g, from the user home, which beats the project's -Xmx2g.

The extra map

Before version catalogs, builds stored shared values in extra properties:

Kotlin
// Kotlin
val springVersion by extra("3.4.0")
extra["owner"] = "platform-team"
val owner = extra["owner"] as String
GROOVY
// Groovy
ext {
    springVersion = '3.4.0'
}
println springVersion

Extra properties live on a project (or its parent) and are visible to child projects. They are untyped and invisible to tools, so for versions prefer a version catalog, and for flags prefer gradle.properties with providers.gradleProperty.

Secrets

Never commit tokens or passwords to gradle.properties in the repository.

  • Put them in ~/.gradle/gradle.properties on your machine, and in CI secrets exposed as ORG_GRADLE_PROJECT_... environment variables.
  • Read them lazily with providers.gradleProperty("repoPassword"), so builds that do not need the secret still work.
  • Do not print them; Gradle does not mask properties in logs.
Kotlin
repositories {
    maven {
        url = uri("https://repo.example.com/releases")
        credentials {
            username = providers.gradleProperty("repoUser").orNull
            password = providers.gradleProperty("repoPassword").orNull
        }
    }
}

Stand-in: parsing a properties file

The real file format is the standard Java .properties format, which Java reads natively. Try changing a line and re-running.

Java Stand-in: reading gradle.properties text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should a personal access token for a private repository be stored?

    Keep secrets out of git: the Gradle user home file or CI secret environment variables are not committed.
  2. 2. The project's gradle.properties says featureFlagBeta=false and you run ./gradlew build -PfeatureFlagBeta=true. Which value does the build see?

    Command-line properties override values from gradle.properties.
  3. 3. Which names in gradle.properties configure Gradle itself?

    Properties such as org.gradle.jvmargs and org.gradle.parallel configure the Gradle runtime.
  4. 4. Why is providers.gradleProperty("x") preferred over project.property("x")?

    The provider reads the value only when needed and records it correctly for caching.

Summary

  • gradle.properties holds key=value settings: org.gradle.* for Gradle itself, other names as project properties.
  • Override on the command line with -Pname=value; environment variables named ORG_GRADLE_PROJECT_name do the same.
  • More specific sources win: command line over user home over project file over script defaults.
  • Read values lazily with providers.gradleProperty(...).
  • Prefer version catalogs over untyped extra for versions.
  • Keep secrets in the user home or CI secrets, never in git.

Next: Lazy Configuration and Providers