Gradle integration - Namespace Documentation

Gradle is a popular build automation tool for Java, Kotlin, Android, and other JVM-based projects. Namespace provides high-performance Gradle build caching with very low network latency between runners and the cache storage. This allows your Gradle workflows to reuse build outputs across runs, significantly reducing build times. Gradle caching is particularly effective for:

Large multi-module projects with many dependencies
Android projects with complex build configurations
Monorepos with shared library modules

Getting started

You can produce a ready-to-use configuration using the CLI:

Configure cache access

nsc cache gradle setup --init-gradle /tmp/init.gradle

This command generates short-term credentials and sets up a Gradle init script that configures remote build caching.

Use the Gradle cache

gradle --init-script=/tmp/init.gradle build

You can pass the init script alongside your existing Gradle configuration.

GitHub Actions Example

jobs:
  build:
    runs-on: namespace-profile-default
    steps:
      - uses: actions/checkout@v4
      - name: Setup Gradle cache
        run: |
          nsc cache gradle setup --init-gradle /tmp/init.gradle
      - name: Gradle build
        run: |
          gradle --init-script=/tmp/init.gradle build

Combining with Cache Volumes

The Gradle build cache stores compilation outputs and task results, but your builds also download dependencies (JARs, plugins, etc.) that are not covered by the build cache. You can use Cache Volumes to persist the Gradle dependency cache across runs, so dependencies don’t need to be re-downloaded each time. Using both together gives you the best performance — Cache Volumes for downloaded dependencies, and the Gradle build cache for build outputs:

jobs:
  build:
    runs-on: namespace-profile-default
    steps:
      - uses: actions/checkout@v4
      - name: Set up Gradle dependency cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: gradle
      - name: Setup Gradle build cache
        run: |
          nsc cache gradle setup --init-gradle /tmp/init.gradle
      - name: Gradle build
        run: |
          gradle --init-script=/tmp/init.gradle build

Using from your local workstation

You can also use Namespace’s Gradle build cache from your local machine. Since the cache is shared, local builds benefit from outputs already cached by CI — and vice versa. First, create a long-term token with access to the cache:

nsc cache gradle create-token --expires_in 7d

Output

Token ID:    tok_...
Name:        gradle-cache--hvc6lmg
Expires At:  2026-01-10T17:51:49+01:00

You can set up your gradle cache config with:
  nsc cache gradle setup --token token.json

This saves the token to token.json in the current directory. Then set up the Gradle cache for your user:

nsc cache gradle setup --token token.json --user

This will generate credentials bound to your current user and configure Gradle’s build cache in your Gradle user home directory. If the current user gets removed from the workspace (or their permissions are reduced), the token becomes invalid. The token can also be revoked ahead of time.

How it works

The Gradle caching solution employs a tiered caching approach, where the hot cache lives as close to the consumer (e.g. your CI job runner) as possible. The cold caching tier is backed by our high-performance artifact storage and enables Gradle to retain a vast amount of cached build outputs. Access to the Gradle cache is granted through short-lived secure credentials.

Usage

Namespace accounts Gradle cache usage in two categories:

Gradle cache storage
Gradle cache reads

For detailed billing information for each item as well as included amounts in your plans, visit the pricing page.

​Getting started

Configure cache access

Use the Gradle cache

​GitHub Actions Example

​Combining with Cache Volumes

​Using from your local workstation

​How it works

​Usage