// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[github_actions]]
= Gradle on GitHub Actions

This page is a reference for integrating Gradle with link:https://github.com/features/actions/[GitHub Actions] using the official link:https://github.com/gradle/actions[`gradle/actions`].

[[github_actions_actions]]
== Available actions

The link:https://github.com/gradle/actions[`gradle/actions`] repository publishes three composable actions.
All examples on this page target the current major version, `v6`.

[cols="1,3",options="header"]
|===
| Action | Purpose

| link:https://github.com/gradle/actions/tree/main/setup-gradle[`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.

| link:https://github.com/gradle/actions/tree/main/dependency-submission[`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.

| link:https://github.com/gradle/actions/tree/main/wrapper-validation[`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`.
|===

[NOTE]
====
`gradle/actions/setup-gradle` is the successor to the deprecated `gradle/gradle-build-action`.
New projects should use `gradle/actions/setup-gradle@v6`.
====

[[github_actions_setup_gradle]]
== Configuring builds with `setup-gradle`

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

[source,yaml]
----
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
----

[[github_actions_setup_gradle_inputs]]
=== Key inputs

[cols="1,3",options="header"]
|===
| 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 link:https://github.com/gradle/actions/blob/main/docs/setup-gradle.md[`setup-gradle` documentation] for the complete input reference.

[[github_actions_caching]]
=== 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`.

[[github_actions_dependency_submission]]
== 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 link:https://docs.github.com/en/rest/dependency-graph/dependency-submission[Dependency Submission API].
Once submitted, the graph powers Dependabot alerts and the Insights → Dependency graph view.

[source,yaml]
----
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"
----

[NOTE]
====
The workflow requires `contents: write` permission to submit the graph. Both *Dependency graph* and *Dependabot alerts* must be enabled in repository settings.
====

[[github_actions_dependency_submission_inputs]]
=== Key inputs

[cols="1,3",options="header"]
|===
| 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 link:https://github.com/gradle/actions/blob/main/docs/dependency-submission.md[`dependency-submission` documentation] for the complete input reference.

[[github_actions_wrapper_validation]]
== 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:

[source,yaml]
----
- uses: gradle/actions/wrapper-validation@v6
----

[[github_actions_build_scans]]
== 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.

[[github_actions_matrix_builds]]
== Matrix builds

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

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