Gradle project

plaintext

Help me get started with Tuist. Follow the setup at:
https://tuist.dev/en/docs/guides/get-started/gradle-project

Follow this path to point an existing Gradle project at Tuist. The dev.tuist Gradle plugin wires Gradle's local build cache to Tuist's remote cache and uploads build and test data to the dashboard, without changing a single ./gradlew command.

Every section below opens with what's missing today and then walks you through the feature that fills the gap.

Prerequisites#

A Gradle project with a settings.gradle.kts (or settings.gradle).
The Tuist command-line interface.

Connect the project#

From the root of the Gradle project, run tuist init. Choose Integrate a Gradle project, then authenticate in the browser and pick the account that should own the project.

bash

tuist init

If you're driving this from a coding agent or a script, run tuist auth login first (the browser flow waits for you to press Enter), then use the non-interactive form:

bash

tuist init --build-system gradle --name <project-handle> --account <account>

Tuist writes a tuist.toml at the repository root with the project handle and prints a plugins { ... } block. Paste it at the top of settings.gradle.kts:

kotlin

plugins {
    id("dev.tuist") version "0.10.0"
}

Sanity-check with ./gradlew help. Gradle should load without errors. If it can't find the plugin, make sure the block is in settings.gradle.kts, not build.gradle.kts.

Everything below is optional and independent.

Remote build cache#

Gradle's local build cache stores task outputs on the machine that produced them. Two developers on the same branch hit the cache in their own ~/.gradle and not each other's, and CI hits a fresh, empty cache every job.

The Tuist remote cache extends the same key/value protocol Gradle already uses across machines. A task's outputs are uploaded on the machine that first executed it and downloaded by anyone else that comes across the same inputs. Enable it in gradle.properties:

plaintext

org.gradle.caching=true

Then build in two environments:

bash

./gradlew clean build --build-cache --info

Cacheable tasks report FROM-CACHE on the second run. Open Cache on the dashboard to see hit rates over time.

Build insights#

Gradle emits task timings at the end of a build, and with --profile writes a per-build HTML report. Neither aggregates across runs. A task that has gotten slower over a series of commits looks the same on any single build's report as it always did.

The dev.tuist plugin uploads task timings for every build to the dashboard automatically once the plugin is applied. There's nothing extra to configure. Open Builds on the dashboard after your next ./gradlew build to see the trend.

Test insights#

Gradle's test reports live per-build under build/reports/tests/. A test that fails intermittently across ten CI runs looks, in any given report, like a stable test that happened to fail once.

Test insights records every task's outcome and duration for every ./gradlew test run and correlates results across runs. Flaky tests, slow tests, and failures surface on the dashboard's Tests tab. When flakes accumulate, quarantine them from the dashboard so they stop blocking merges.

The plugin also supports a stress-testing mode that reruns test cases a build introduces and flags any that prove flaky before they land. Add it to the tuist extension in settings.gradle.kts:

kotlin

tuist {
    stressNewTests {
        mode = "report" // or "enforce"
    }
}

Bundle insights#

The Android Gradle Plugin reports the size of the produced .aab in the build output. That number disappears with the branch, and comparing sizes across releases is a manual accounting job. Play Console reports the same numbers, but only after the artifact has been uploaded.

Bundle insights records install and download sizes for every .aab (recommended) or .apk and can fail a PR check when a per-branch threshold is breached. Add this to your CI right after your build step:

bash

tuist inspect bundle App.aab

Open Bundle insights → Android on the dashboard to see the trend and configure thresholds.

Previews#

Play Console's internal test track adds a review-and-propagation delay on every share. Sending a raw .apk through Slack or email is faster but loses track of which build a specific message refers to.

Previews turns a build into a shareable link that recipients install with one command:

bash

tuist share App.apk

Bring the team along#

Cache hits, insights, and stress-testing all compound with the number of people connected to the project. Invite your teammates to the organization from the account settings on the dashboard, and set up Single Sign-On (Google, Okta, Microsoft) so onboarding is a click rather than a per-person tuist auth login.

For CI, don't use a personal login. Set TUIST_TOKEN scoped to your project (create it from the project settings on the dashboard).

Full plugin reference#

Everything covered here is the minimum to get value out of Tuist on a Gradle project. Configuration options for the tuist extension block, stressNewTests mode, and CI authentication live in the Install the Gradle plugin reference.