gradle/actions/setup-gradle

Configure Gradle for GitHub Actions with dependency caching, wrapper validation, and build scans.

Official actionCategory: Language & Toolchain SetupLatest v6View on GitHub

What it does

gradle/actions/setup-gradle prepares the runner for Gradle builds: it restores and saves Gradle User Home caches, validates wrapper jars by default, and adds a job summary of executed builds.

It configures the environment rather than running the build; you still invoke ./gradlew in a later step. Install a JDK first with actions/setup-java.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-java@v4
    with:
      distribution: temurin
      java-version: 21
  - uses: gradle/actions/setup-gradle@v6
  - run: ./gradlew build

Inputs

Input	Description	Default	Required
`gradle-version`	Gradle version to download and add to PATH. If not provided, the project's Gradle Wrapper is assumed.	-	No
`cache-disabled`	When true, all caching is disabled.	`false`	No
`cache-read-only`	When true, cache entries are read but never written. Defaults to false on the default branch and true on other branches.	`${{ github.event.repository != null && github.ref_name != github.event.repository.default_branch }}`	No
`cache-encryption-key`	Base64-encoded AES key used to encrypt configuration-cache data. Without it, configuration-cache data is not saved/restored.	-	No
`dependency-graph`	Whether to generate/submit a GitHub dependency snapshot: disabled, generate, generate-and-submit, and more.	`disabled`	No
`add-job-summary`	When to include a Job Summary in the action results: never, always, on-failure.	`always`	No
`build-scan-publish`	Set to true to publish build results as a Build Scan on scans.gradle.com (requires agreeing to the terms of use).	`false`	No
`validate-wrappers`	When true (the default), validates all wrapper jars found in the repository and fails on invalid checksums.	`true`	No

Outputs

Output	Description
`build-scan-url`	Link to the Build Scan generated by a Gradle build. Applies to the step executing Gradle, not the setup step itself.
`dependency-graph-file`	Path to the GitHub Dependency Graph snapshot file generated by a Gradle build.
`gradle-version`	Version of Gradle that was set up by the action.

Notes

Cache writes default to the repository default branch only (cache-read-only is true elsewhere), so PR branches reuse the main-branch cache instead of polluting it.

Gradle configuration-cache data is only saved/restored when cache-encryption-key is provided.

Common errors

Wrapper validation failing the job means a gradle-wrapper.jar in the repo does not match a known Gradle checksum; regenerate the wrapper with ./gradlew wrapper or, for nightly wrappers, set allow-snapshot-wrappers: true.
Builds appearing to never hit the cache on feature branches is usually the cache-read-only default: entries are only written from the default branch, so seed the cache with a run on main.
Dependency-graph submission failing with a permissions error means the workflow lacks contents: write (required by the Dependency Submission API) for the submit modes.

Security and pinning

Pin the action to a commit SHA. If you use cache-encryption-key, store it in a secret; it is exported as GRADLE_ENCRYPTION_KEY for later steps.

Alternatives and related

actions/setup-javaInstall a JDK (Temurin, Zulu, Corretto, and more) and cache Maven or Gradle dependencies. actions/cacheCache any files between workflow runs, keyed on a hash of your lockfiles.

Frequently asked questions

Does setup-gradle run my build?

No. It configures caching, validation, and reporting; you run the build yourself in a later step, normally via the checked-in Gradle Wrapper (./gradlew build).

References

GitHub Actions documentation