This page is a reference for integrating Gradle with GitHub Actions using the official gradle/actions.

Available actions

The gradle/actions repository publishes three composable actions. All examples on this page target the current major version, v6.

Action Purpose

gradle/actions/setup-gradle

Configures the runner for Gradle builds. Restores and saves the Gradle User Home cache, validates the Gradle Wrapper, and captures Build Scan® links in the job summary.

gradle/actions/dependency-submission

Generates a dependency graph for the project and submits it to the GitHub Dependency Submission API, enabling Dependabot alerts and supply-chain security features.

gradle/actions/wrapper-validation

Validates the checksum of every gradle-wrapper.jar in the repository. setup-gradle runs this check automatically; use this action standalone when you do not need the rest of setup-gradle.

gradle/actions/setup-gradle is the successor to the deprecated gradle/gradle-build-action. New projects should use gradle/actions/setup-gradle@v6.

Configuring builds with setup-gradle

A minimal workflow that builds a Gradle project and publishes a Build Scan:

name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21

      - uses: gradle/actions/setup-gradle@v6
        with:
          build-scan-publish: true
          build-scan-terms-of-use-url: "https://gradle.com/terms-of-service"
          build-scan-terms-of-use-agree: "yes"

      - run: ./gradlew build

Key inputs

Input Description

gradle-version

Gradle version to provision on the runner. Accepts an explicit version (e.g. 8.14) or an alias: wrapper (default), current, release-candidate, nightly, release-nightly.

cache-provider

Caching backend. enhanced (default, optimized proprietary cache — free for public repos) or basic (open-source wrapper over actions/cache). New in v6.

cache-disabled

Set to true to disable all caching.

cache-read-only

Read cache entries but do not write them back. Typical for feature branches so only the default branch updates the cache.

cache-write-only

Start with a clean Gradle User Home and save state at job end. Useful for seeding a fresh cache.

cache-cleanup

Purge unused files from Gradle User Home before saving. One of always, on-success (default), or never.

cache-encryption-key

Base64-encoded AES key used to encrypt configuration-cache entries, which may contain credentials. Required to cache the configuration cache across jobs.

gradle-home-cache-includes / gradle-home-cache-excludes

Glob patterns that add to or subtract from the set of Gradle User Home paths that are cached.

build-scan-publish

When true, publishes a Build Scan for every Gradle invocation in the job.

build-scan-terms-of-use-url / build-scan-terms-of-use-agree

Required when build-scan-publish is enabled. Set the URL to https://gradle.com/terms-of-service and agreement to yes.

develocity-access-key

Access key for publishing Build Scans to a private Develocity server. Provide via secrets.

add-job-summary

Controls the GitHub Actions job summary produced by the action: always (default), on-failure, or never.

add-job-summary-as-pr-comment

Mirror the job summary as a pull-request comment: never (default), on-failure, or always.

See the setup-gradle documentation for the complete input reference.

Caching behavior

setup-gradle automatically saves and restores the Gradle User Home (~/.gradle), which contains the Gradle distribution, resolved dependencies, and the local build cache. A cache entry is written at job completion when the job is a push to the default branch; other jobs restore from existing entries.

Starting with version 6.1.0, the default cache backend is the enhanced provider, which offers higher hit rates than the standard GitHub Actions cache. Set cache-provider: basic to use the fully open-source implementation over actions/cache.

Submitting dependency graphs

The dependency-submission action runs the Gradle build in a dedicated mode that captures the resolved dependency graph, then submits it to GitHub via the Dependency Submission API. Once submitted, the graph powers Dependabot alerts and the Insights → Dependency graph view.

name: Dependency Submission

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  dependency-submission:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21

      - uses: gradle/actions/dependency-submission@v6
        with:
          build-scan-publish: true
          build-scan-terms-of-use-url: "https://gradle.com/terms-of-service"
          build-scan-terms-of-use-agree: "yes"

The workflow requires contents: write permission to submit the graph. Both Dependency graph and Dependabot alerts must be enabled in repository settings.

Key inputs

Input Description

dependency-graph

What to do with the generated graph: generate-and-submit (default), generate-and-upload (save as workflow artifact only), generate-submit-and-upload, or clear to remove previously submitted graphs.

dependency-graph-continue-on-failure

If true, a failure to generate or submit the graph does not fail the job.

dependency-graph-include-projects / -exclude-projects

Regex filters on Gradle subproject paths, e.g. :app or :libs:.*.

dependency-graph-include-configurations / -exclude-configurations

Regex filters on configuration names, e.g. exclude testRuntimeClasspath from the submitted graph.

dependency-resolution-task

Task used to resolve dependencies. Defaults to the built-in GitHubDependencyGraphPlugin resolution; override only if a custom task is required.

additional-arguments

Extra arguments appended to the Gradle invocation (for example --no-configuration-cache).

build-root-directory

Path to the Gradle build if it is not at the repository root.

artifact-retention-days

Retention for uploaded dependency-graph artifacts (default 30).

See the dependency-submission documentation for the complete input reference.

Validating the Gradle Wrapper

setup-gradle validates every gradle-wrapper.jar in the repository on each run. Projects that do not otherwise use setup-gradle (for example, those building with a pre-installed Gradle distribution) can run the standalone action:

- uses: gradle/actions/wrapper-validation@v6

Build Scans in job summaries

When setup-gradle or dependency-submission detects a published Build Scan, it appends the scan link and a task-execution summary to the GitHub Actions job summary. Use add-job-summary-as-pr-comment: on-failure to surface the same information on the pull request when a build fails.

Matrix builds

For matrix builds, use cache-read-only: true on non-primary matrix legs so only one leg writes to the cache:

strategy:
  matrix:
    java: [17, 21]
steps:
  - uses: gradle/actions/setup-gradle@v6
    with:
      cache-read-only: ${{ matrix.java != 21 }}