Why a Local Repository Matters

Gradle keeps a cache of every resolved artifact, but some times you need an explicit, isolated directory that behaves like a full-blown Maven repository on disk. Typical reasons:

• Air-gapped CI runners that cannot reach the internet.
• Reproducible builds across teams by locking every depenedncy to a single folder.
• Faster CI runs by copying the folder into the build container instead of re-downloading.

Declaring the Repository Path

Via gradle.properties (persistent)

# ~/.gradle/gradle.properties or project-root/gradle.properties
systemProp.org.gradle.internal.repository.local=/opt/gradle-offline-repo

Via Environment Variable (ephemeral)

export GRADLE_REPO_LOCAL=/tmp/ci-cache
./gradlew assemble

Via Command-Line Flag (one-off)

./gradlew build -Dorg.gradle.internal.repository.local=/Volumes/ssd/gradle-cache

Gradle will create missing directories automatically; no manual mkdir required.

Registering the Folder as a Repository

// build.gradle.kts
repositories {
    maven {
        name = "LocalMirror"
        url = uri(System.getProperty("org.gradle.internal.repository.local"))
    }
    // Fallbacks only when online
    if (!gradle.startParameter.isOffline) {
        mavenCentral()
    }
}

Publishing to the Local Store

// publish.gradle.kts
publishing {
    publications {
        create<MavenPublication>("local") {
            from(components["java"])
            groupId = "com.acme"
            artifactId = "sdk"
            version = "1.4.2"
        }
    }
    repositories {
        maven {
            name = "LocalDeploy"
            url = uri(System.getProperty("org.gradle.internal.repository.local"))
        }
    }
}

Run:

./gradlew publishLocalDeployPublicationToLocalDeployRepository

Offline Mode

./gradlew build --offline

Gradle skips every remote repository and resolves exclusively against the local folder.

Pruning Stale Artifacts

#!/usr/bin/env bash
REPO="${GRADLE_REPO_LOCAL:-/opt/gradle-offline-repo}"
find "$REPO" -type f -mtime +90 -name "*.jar" -delete
find "$REPO" -type d -empty -delete

Schedule the script via cron or a CI maintenance job.

Multi-Project Setup

// settings.gradle.kts
rootProject.name = "platform"
include(":core", ":service")

gradle.allprojects {
    repositories {
        maven {
            name = "SharedLocal"
            url = uri(System.getProperty("org.gradle.internal.repository.local")
        }
    }
}
```\n
All subprojects inherit the same repositoyr, guaranteeing identical resolution results.

## Quick Checklist

- Add the property toore any build runs.
- Publish snapshots and releases to the same directory.
- Keep the folder under version control (LFS) if you need historical states.
- Rotate old artifacts to prevent unbounded growth.