> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gradle integration

Gradle is a popular build automation tool for Java, Kotlin, Android, and other JVM-based projects.

Namespace provides high-performance [Gradle](https://gradle.org) 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](/docs/reference/cli/installation):

<Steps titleSize="h3">
  <Step title="Configure cache access">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Use the Gradle cache">
    ```bash theme={null}
    gradle --init-script=/tmp/init.gradle build
    ```

    You can pass the init script alongside your existing Gradle configuration.
  </Step>
</Steps>

### GitHub Actions Example

```yaml theme={null}
jobs:
  build:
    runs-on: namespace-profile-default
    steps:
      - uses: actions/checkout@v4
      - name: Setup Gradle cache # [!code ++:3]
        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](/docs/solutions/github-actions/caching) 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:

```yaml theme={null}
jobs:
  build:
    runs-on: namespace-profile-default
    steps:
      - uses: actions/checkout@v4
      - name: Set up Gradle dependency cache # [!code ++:4]
        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:

```bash theme={null}
nsc cache gradle create-token --expires_in 7d
```

```text nocopy Output theme={null}
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:

```bash theme={null}
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](/docs/architecture/storage/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](https://namespace.so/pricing).