Gradle cache

Tuist provides a Gradle plugin that integrates with Gradle's built-in build cache to share build artifacts remotely. When a task's outputs are already cached, Gradle skips execution and pulls the result from Tuist's remote cache, saving build time across your team and CI environments.

REQUIREMENTS

• The Tuist Gradle plugin installed and configured

Once the Tuist Gradle plugin is installed, you also need to enable Gradle's build cache in your gradle.properties file:

org.gradle.caching=true

Without this, Gradle does not activate its build cache subsystem — even with a remote cache configured — and all tasks will execute without hitting or populating the cache. Once enabled, Gradle will use Tuist as a remote build cache, downloading cached task outputs on cache hits and uploading them after task execution.

Cache upload policy

By default, the plugin both downloads and uploads artifacts to the remote cache. You can control uploads with the push option in the buildCache block:

tuist {
    buildCache {
        push = false // read-only mode
    }
}

A common pattern is to push artifacts only from CI, where builds are reproducible, while keeping local environments read-only:

tuist {
    buildCache {
        push = System.getenv("CI") != null
    }
}

With this setup, local builds benefit from cached artifacts without uploading, while CI builds populate the cache for the rest of the team.

Continuous integration

For CI environments, authenticate using one of the methods in the Authentication guide. See the Continuous Integration guide for provider-specific CI examples.

Disabling the local build cache

Gradle maintains both a local and a remote build cache. The local build cache stores task outputs on disk under ~/.gradle/caches/build-cache-1.

When Tuist is configured as the remote build cache, it is recommended to disable the local build cache on CI. This avoids storing redundant artifacts on CI runners and ensures builds always populate the remote cache with fresh entries for the rest of the team.

Disable Gradle's local build cache on CI in your settings.gradle.kts:

buildCache {
    local {
        isEnabled = System.getenv("CI") == null
    }
}

This keeps the local build cache available for local development while disabling it on CI, where Tuist's remote cache handles artifact sharing.

Configuration reference

The buildCache block supports:

Option	Type	Default	Description
enabled	Boolean	true	Whether the remote build cache is enabled.
push	Boolean	true	Whether to upload task outputs to the remote cache.
allowInsecureProtocol	Boolean	false	Whether to allow insecure HTTP connections.