actions/gradle
1
0
Fork 0
mirror of https://github.com/gradle/actions.git synced 2026-04-19 18:12:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add open-source 'basic' cache provider and revamp licensing documentation (#930)

Browse Source 
## Summary

- **New `basic` cache provider**: Adds an open-source (MIT-licensed)
caching implementation built on `@actions/cache` as an alternative to
the proprietary Enhanced Caching. Users can opt in with `cache-provider:
basic` on both `setup-gradle` and `dependency-submission` actions.
- **Revamped licensing & distribution docs**: Replaces the verbose
licensing notice block (previously shown in README, docs, and logs) with
a friendlier callout and a new dedicated
[DISTRIBUTION.md](./DISTRIBUTION.md) covering component licensing, usage
tiers, data privacy ("Safe Harbor"), and opt-out instructions.
- **Improved messaging**: Enhanced Caching and Basic Caching each
display concise, informative log messages and job summary notes instead
of the previous wall-of-text license warning.
- **New integration tests**: Adds `integ-test-basic-cache-provider.yml`
workflow that seeds and verifies the basic cache provider across
platforms, plus unit tests for `BasicCacheService` and `getCacheService`
selection logic.
- **CI workflow reorganization**: Dependency-submission integration
tests extracted into their own reusable suite
(`suite-integ-test-dependency-submission.yml`); sample project tests
moved into the caching suite.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Daz DeBoer
2026-04-02 21:36:01 -06:00
committed by GitHub
parent ac396bf1a8
commit ff9ae24c39
23 changed files with 723 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci-integ-test-full.yml
+10
View File
@@ -24,6 +24,16 @@ jobs:
skip-dist: true
secrets: inherit
dependency-submission-integ-tests:
uses: ./.github/workflows/suite-integ-test-dependency-submission.yml
concurrency:
group: CI-integ-test-full
cancel-in-progress: false
with:
runner-os: '["ubuntu-latest", "windows-latest", "macos-latest"]'
skip-dist: true
secrets: inherit
other-integ-tests:
permissions:
contents: write
.github/workflows/ci-integ-test.yml
+15 -3
View File
@@ -28,7 +28,7 @@ jobs:
needs: build-distribution
uses: ./.github/workflows/suite-integ-test-caching.yml
concurrency:
group: CI-integ-test
group: CI-integ-test-caching
cancel-in-progress: false
with:
skip-dist: false
@@ -37,10 +37,22 @@ jobs:
other-integ-tests:
permissions:
contents: write
needs: build-distribution
needs: caching-integ-tests
uses: ./.github/workflows/suite-integ-test-other.yml
concurrency:
group: CI-integ-test
group: CI-integ-test-other
cancel-in-progress: false
with:
skip-dist: false
secrets: inherit
dependency-submission-integ-tests:
permissions:
contents: write
needs: other-integ-tests
uses: ./.github/workflows/suite-integ-test-dependency-submission.yml
concurrency:
group: CI-integ-test-dependency-submission
cancel-in-progress: false
with:
skip-dist: false
.github/workflows/demo-job-summary.yml
+17
View File
@@ -132,6 +132,23 @@ jobs:
working-directory: .github/workflow-samples/kotlin-dsl
run: ./gradlew assemble
basic-caching:
needs: build-distribution
runs-on: ubuntu-latest
steps:
- name: Checkout sources
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- name: Initialize integ-test
uses: ./.github/actions/init-integ-test
- name: Setup Gradle
uses: ./setup-gradle
with:
cache-provider: basic
- name: Build kotlin-dsl project
working-directory: .github/workflow-samples/kotlin-dsl
run: ./gradlew assemble
terms-of-use-accepted:
needs: build-distribution
runs-on: ubuntu-latest
.github/workflows/integ-test-basic-cache-provider.yml
+67
View File
@@ -0,0 +1,67 @@
name: Test basic cache provider
on:
workflow_call:
inputs:
cache-key-prefix:
type: string
default: '0'
runner-os:
type: string
default: '["ubuntu-latest"]'
skip-dist:
type: boolean
default: false
env:
SKIP_DIST: ${{ inputs.skip-dist }}
GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: basic-cache-provider-${{ inputs.cache-key-prefix }}
permissions:
contents: read
jobs:
basic-cache-seed-build:
strategy:
max-parallel: 1
fail-fast: false
matrix:
os: ${{fromJSON(inputs.runner-os)}}
runs-on: ${{ matrix.os }}
steps:
- name: Checkout sources
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- name: Initialize integ-test
uses: ./.github/actions/init-integ-test
- name: Setup Gradle with basic cache provider
uses: ./setup-gradle
with:
cache-provider: basic
cache-read-only: false # For testing, allow writing cache entries on non-default branches
- name: Build kotlin-dsl project
working-directory: .github/workflow-samples/kotlin-dsl
run: ./gradlew build
basic-cache-verify-build:
needs: basic-cache-seed-build
strategy:
max-parallel: 1
fail-fast: false
matrix:
os: ${{fromJSON(inputs.runner-os)}}
runs-on: ${{ matrix.os }}
steps:
- name: Checkout sources
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- name: Initialize integ-test
uses: ./.github/actions/init-integ-test
- name: Setup Gradle with basic cache provider
uses: ./setup-gradle
with:
cache-provider: basic
cache-read-only: true
- name: Build kotlin-dsl project
working-directory: .github/workflow-samples/kotlin-dsl
run: ./gradlew build --offline
.github/workflows/suite-integ-test-caching.yml
+18
View File
@@ -45,3 +45,21 @@ jobs:
uses: ./.github/workflows/integ-test-restore-java-toolchain.yml
with:
skip-dist: ${{ inputs.skip-dist }}
sample-kotlin-dsl:
uses: ./.github/workflows/integ-test-sample-kotlin-dsl.yml
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
sample-gradle-plugin:
uses: ./.github/workflows/integ-test-sample-gradle-plugin.yml
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
basic-cache-provider:
uses: ./.github/workflows/integ-test-basic-cache-provider.yml
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
.github/workflows/suite-integ-test-dependency-submission.yml
+43
View File
@@ -0,0 +1,43 @@
name: suite-integ-test-dependency-submission
on:
workflow_call:
inputs:
runner-os:
type: string
default: '["ubuntu-latest"]'
skip-dist:
type: boolean
default: false
permissions:
contents: read
jobs:
dependency-graph:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-dependency-graph.yml
permissions:
contents: write
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
dependency-submission:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-dependency-submission.yml
permissions:
contents: write
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
dependency-submission-failures:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-dependency-submission-failures.yml
permissions:
contents: write
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
.github/workflows/suite-integ-test-other.yml
-39
View File
@@ -20,33 +20,6 @@ jobs:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
dependency-graph:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-dependency-graph.yml
permissions:
contents: write
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
dependency-submission:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-dependency-submission.yml
permissions:
contents: write
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
dependency-submission-failures:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-dependency-submission-failures.yml
permissions:
contents: write
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
develocity-injection:
if: ${{ ! github.event.pull_request.head.repo.fork }}
uses: ./.github/workflows/integ-test-inject-develocity.yml
@@ -61,18 +34,6 @@ jobs:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
sample-kotlin-dsl:
uses: ./.github/workflows/integ-test-sample-kotlin-dsl.yml
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
sample-gradle-plugin:
uses: ./.github/workflows/integ-test-sample-gradle-plugin.yml
with:
runner-os: '${{ inputs.runner-os }}'
skip-dist: ${{ inputs.skip-dist }}
toolchain-detection:
uses: ./.github/workflows/integ-test-detect-toolchains.yml
with:
CLAUDE.md
+6
View File
@@ -17,6 +17,12 @@ Do not treat `actions/sources/vendor/gradle-actions-caching` as the source of tr
## Building
Before running any build or npm commands, initialize the PATH:
```sh
source ~/.zshrc
```
To build this repository, run the `build` script at the root of that repository with no arguments:
```sh
DISTRIBUTION.md
+50
View File
@@ -0,0 +1,50 @@
# Distribution and Licensing of gradle/actions
This document provides a clear breakdown of the components within the `gradle/actions` repository, their respective licenses, and how we handle data and privacy. Our goal is to provide the best possible experience for running Gradle on GitHub Actions while maintaining our commitment to the open-source community.
## 1. Component Map
The `gradle/actions` project consists of three primary components:
| Component | License | Source | Description |
| :--- | :--- | :--- | :--- |
| **Action Runner** | **[MIT](LICENSE)** | Open | The core action logic: configures a local Gradle installation, performs wrapper validation, and reports on Gradle build execution. |
| **Basic Caching** | **[MIT](LICENSE)** | Open | Configures basic Gradle User Home caching using 'actions/cache'. |
| **Enhanced Caching** | **[Proprietary](NOTICE)** | Closed | Uses the 'gradle-actions-caching' library to provide fine-grained caching of Gradle User Home, intelligent cache cleanup and other advanced features. |
By default, **Enhanced Caching** is enabled to provide the best experience.
## 2. The "Safe Harbor" Clause (Data Privacy)
The proprietary components of this action are governed by the **[Gradle Technologies Terms of Use](https://gradle.com/legal/gradle-technologies-terms-of-use/)**. We have updated these terms to include a specific safe harbor for users of `gradle-actions-caching`.
> **Plain English Summary:** Gradle does not claim ownership of any code, build artifacts, or other content processed by the caching library. These remain your sole property. We only use metadata (like cache keys) to facilitate the caching service.
## 3. Usage Tiers
To support the development of high-performance CI tooling, we offer the following usage model:
* **Public Repositories:**
* Both **Basic** and **Enhanced** caching are free forever. We are committed to supporting the open-source ecosystem at no cost.
* **Private Repositories:**
* **Basic Caching** is free forever under the MIT license.
* **Enhanced Caching** is currently in a **Free Preview** phase. We plan to introduce usage-based pricing for large-scale commercial organizations in the future.
While we haven't finalized specific usage thresholds yet, our intent is to keep Enhanced Caching free for individual developers and small teams. We are currently in a learning phase to ensure that future restrictions are focused on large-scale commercial users of the product. No matter how these limits evolve, the open-source Basic Caching provider will always remain a free, functional alternative for everyone.
## 4. Your Choice: Basic vs. Enhanced
We believe in user autonomy. If you do not wish to use proprietary code or accept the Gradle Technologies Terms of Use, you can opt-out of enhanced caching with a single line of configuration:
```yaml
- uses: gradle/actions/setup-gradle@v6
with:
cache-provider: basic # Switches to the MIT-licensed open-source implementation
```
> [!IMPORTANT]
> ## Licensing notice
>
> The software in this repository, except for the bundled `gradle-actions-caching` component, is licensed under the [MIT License](LICENSE).
>
> The caching functionality in this project has been extracted into `gradle-actions-caching`, a proprietary commercial component that is not covered by the MIT License for this repository.
>
> Use of the `gradle-actions-caching` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
>
> The `gradle-actions-caching` component is used only when enhanced caching is enabled and is not loaded or used with basic caching or when caching is disabled.
LICENSE
+11
View File
@@ -1,3 +1,14 @@
Note on Repository Contents:
The software in this repository is primarily licensed under the MIT License (see below).
However, this repository includes a vendor-included component, 'gradle-actions-caching',
which is Proprietary and subject to the Gradle Technologies Terms of Use
(https://gradle.com/legal/gradle-technologies-terms-of-use/).
For a detailed breakdown of which components are Open Source (MIT) and which are
Proprietary, please refer to DISTRIBUTION.md and NOTICE.
-------------------------------------------------------------------------
The MIT License (MIT)
NOTICE
+4 -4
View File
@@ -3,9 +3,9 @@ NOTICE
The software in this repository, except for the bundled `gradle-actions-caching` component, is licensed under the MIT License.
The caching functionality in this project has been extracted into `gradle-actions-caching`, a proprietary commercial component that is not covered by the MIT License for this repository.
The bundled `gradle-actions-caching` component is licensed and governed by a separate license, available at https://gradle.com/legal/terms-of-use/.
The `gradle-actions-caching` component is used only when caching is enabled and is not loaded or used when caching is disabled.
The `gradle-actions-caching` component is used only when enhanced caching is enabled and is not loaded or used with basic caching or when caching is disabled.
Use of the `gradle-actions-caching` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
If you do not agree to these license terms, do not use the gradle-actions-caching component.
Use the `gradle-actions-caching` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
For a detailed breakdown of components, licensing tiers, and data privacy terms, see DISTRIBUTION.md.
README.md
+6 -13
View File
@@ -2,21 +2,14 @@
This repository contains a set of GitHub Actions that are useful for building Gradle projects on GitHub.
> [!IMPORTANT]
> ## Licensing notice
> [!NOTE]
> ### ⚡️ Choice of caching providers in v6
> To provide the fastest possible build experience this action includes **Enhanced Caching** via `gradle-actions-caching`, an optimized provider powered by proprietary technology. This feature is **free for all public repositories** and is currently available as a **Free Preview** for private repositories.
>
> The software in this repository is licensed under the [MIT License](LICENSE).
> **Prefer a 100% Open Source (MIT) path?**
> We also provide a **Basic Caching** provider as a thin wrapper over `actions/cache`. This provider is **free for all repositories** (public and private) and can be enabled at any time by setting `cache-provider: basic`.
>
> The caching functionality in this project has been extracted into `gradle-actions-caching`, a proprietary commercial component that is not covered by the MIT License for this repository.
> The bundled `gradle-actions-caching` component is licensed and governed by a separate license, available at https://gradle.com/legal/terms-of-use/.
>
> The `gradle-actions-caching` component is used only when caching is enabled and is not loaded or used when caching is disabled.
>
> Use of the `gradle-actions-caching` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
> If you do not agree to these license terms, do not use the `gradle-actions-caching` component.
This license notice will be displayed in workflow logs and each job summary. To suppress this message,
either [accept the terms of use](docs/setup-gradle.md#publishing-to-scansgradlecom) in your workflow, or [provide a Develocity access key](docs/setup-gradle.md#managing-develocity-access-keys).
> For a full breakdown of the components, usage tiers, and our **Safe Harbor** data privacy commitment, see our [Distribution & Licensing Guide](./DISTRIBUTION.md).
## The `setup-gradle` action
dependency-submission/action-types.yml
+6
View File
@@ -14,6 +14,12 @@ inputs:
type: string
# Cache configuration
cache-provider:
type: enum
allowed-values:
- basic
- enhanced
cache-disabled:
type: boolean
dependency-submission/action.yml
+8
View File
@@ -26,6 +26,14 @@ inputs:
required: false
# Cache configuration
cache-provider:
description: |
Specifies the caching implementation to use.
'enhanced' (default) uses the full-featured commercial caching service (gradle-actions-caching).
'basic' uses a simple open-source caching implementation based on GitHub Actions cache.
required: false
default: 'enhanced'
cache-disabled:
description: When 'true', all caching is disabled. No entries will be written to or read from the cache.
required: false
docs/dependency-submission.md
+10 -13
View File
@@ -15,21 +15,14 @@ for vulnerable dependencies, as well as to populate the
If you're confused by the behaviour you're seeing or have specific questions, please check out [the FAQ](dependency-submission-faq.md) before raising an issue.
> [!IMPORTANT]
> ## Licensing notice
> [!NOTE]
> ### ⚡️ Choice of caching providers in v6
> To provide the fastest possible build experience this action includes **Enhanced Caching** via `gradle-actions-caching`, an optimized provider powered by proprietary technology. This feature is **free for all public repositories** and is currently available as a **Free Preview** for private repositories.
>
> The software in this repository is licensed under the [MIT License](LICENSE).
> **Prefer a 100% Open Source (MIT) path?**
> We also provide a **Basic Caching** provider as a thin wrapper over `actions/cache`. This provider is **free for all repositories** (public and private) and can be enabled at any time by setting `cache-provider: basic`.
>
> The caching functionality in this project has been extracted into `gradle-actions-caching`, a proprietary commercial component that is not covered by the MIT License for this repository.
> The bundled `gradle-actions-caching` component is licensed and governed by a separate license, available at https://gradle.com/legal/terms-of-use/.
>
> The `gradle-actions-caching` component is used only when caching is enabled and is not loaded or used when caching is disabled.
>
> Use of the `gradle-actions-caching` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
> If you do not agree to these license terms, do not use the `gradle-actions-caching` component.
This license notice will be displayed in workflow logs and each job summary. To suppress this message,
either [accept the terms of use](setup-gradle.md#publishing-to-scansgradlecom) in your workflow, or [provide a Develocity access key](setup-gradle.md#managing-develocity-access-keys).
> For a full breakdown of the components, usage tiers, and our **Safe Harbor** data privacy commitment, see our [Distribution & Licensing Guide](./DISTRIBUTION.md).
## General usage
@@ -76,6 +69,10 @@ on the command-line will be used.
The action provides the ability to override the Gradle version and task to execute, as well as provide
additional arguments that will be passed to Gradle on the command-line. See [Configuration Parameters](#configuration-parameters) below.
### Selecting a cache provider
See [Selecting a cache provider](setup-gradle.md#selecting-a-cache-provider) for details on choosing between the `enhanced` (default) and `basic` cache providers via the `cache-provider` input.
### Disabling caching
Caching is enabled by default. You can disable caching for the action as follows:
docs/setup-gradle.md
+21 -13
View File
@@ -2,21 +2,14 @@
This GitHub Action can be used to configure Gradle for optimal execution on any platform supported by GitHub Actions.
> [!IMPORTANT]
> ## Licensing notice
> [!NOTE]
> ### ⚡️ Choice of caching providers in v6
> To provide the fastest possible build experience this action includes **Enhanced Caching** via `gradle-actions-caching`, an optimized provider powered by proprietary technology. This feature is **free for all public repositories** and is currently available as a **Free Preview** for private repositories.
>
> The software in this repository is licensed under the [MIT License](LICENSE).
> **Prefer a 100% Open Source (MIT) path?**
> We also provide a **Basic Caching** provider as a thin wrapper over `actions/cache`. This provider is **free for all repositories** (public and private) and can be enabled at any time by setting `cache-provider: basic`.
>
> The caching functionality in this project has been extracted into `gradle-actions-caching`, a proprietary commercial component that is not covered by the MIT License for this repository.
> The bundled `gradle-actions-caching` component is licensed and governed by a separate license, available at https://gradle.com/legal/terms-of-use/.
>
> The `gradle-actions-caching` component is used only when caching is enabled and is not loaded or used when caching is disabled.
>
> Use of the `gradle-actions-caching` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
> If you do not agree to these license terms, do not use the `gradle-actions-caching` component.
This license notice will be displayed in workflow logs and each job summary. To suppress this message,
either [accept the terms of use](#publishing-to-scansgradlecom) in your workflow, or [provide a Develocity access key](#managing-develocity-access-keys).
> For a full breakdown of the components, usage tiers, and our **Safe Harbor** data privacy commitment, see our [Distribution & Licensing Guide](./DISTRIBUTION.md).
## Why use the `setup-gradle` action?
@@ -133,6 +126,21 @@ To reduce the space required for caching, this action attempts to reduce duplica
The state will be restored from the cache during the first `setup-gradle` step for any workflow job, and cache entries will be written back to the cache at the end of the job after all Gradle executions have been completed.
### Selecting a cache provider
The `setup-gradle` action offers two caching components, offered under different license terms and with different features.
See [DISTRIBUTION.md](../DISTRIBUTION.md) for more details.
You choose which cache to use via the `cache-provider` input:
- **`enhanced`** (default): Uses the full-featured commercial `gradle-actions-caching` library. Provides advanced features like fine-grained cache entries and intelligent cache cleanup.
- **`basic`**: A fully open-source caching implementation built on the standard GitHub Actions cache (`@actions/cache`). Caches the `~/.gradle/caches` and `~/.gradle/wrapper` directories using a cache key based on your Gradle build files (same strategy as `actions/setup-java` with `cache: gradle`).
```yaml
# Use the open-source basic cache provider
cache-provider: basic
```
### Disabling caching
Caching is enabled by default. You can disable caching for the action as follows:
setup-gradle/action-types.yml
+6
View File
@@ -4,6 +4,12 @@ inputs:
type: string
# Cache configuration
cache-provider:
type: enum
allowed-values:
- basic
- enhanced
cache-disabled:
type: boolean
setup-gradle/action.yml
+8
View File
@@ -9,6 +9,14 @@ inputs:
required: false
# Cache configuration
cache-provider:
description: |
Specifies the caching implementation to use.
'enhanced' (default) uses the full-featured commercial caching service (gradle-actions-caching).
'basic' uses a simple open-source caching implementation based on GitHub Actions cache.
required: false
default: 'enhanced'
cache-disabled:
description: When 'true', all caching is disabled. No entries will be written to or read from the cache.
required: false
sources/src/cache-service-basic.ts
+85
View File
@@ -0,0 +1,85 @@
import * as cache from '@actions/cache'
import * as core from '@actions/core'
import * as glob from '@actions/glob'
import * as path from 'path'
import {BuildResult} from './build-results'
import {CacheOptions, CacheService} from './cache-service'
const PRIMARY_KEY_STATE = 'BASIC_CACHE_PRIMARY_KEY'
const RESTORED_KEY_STATE = 'BASIC_CACHE_RESTORED_KEY'
const CACHE_KEY_PREFIX = 'setup-java'
const GRADLE_BUILD_FILE_PATTERNS = [
'**/*.gradle*',
'**/gradle-wrapper.properties',
'buildSrc/**/Versions.kt',
'buildSrc/**/Dependencies.kt',
'gradle/*.versions.toml',
'**/versions.properties'
]
export class BasicCacheService implements CacheService {
async restore(gradleUserHome: string, _cacheOptions: CacheOptions): Promise<void> {
const cachePaths = getCachePaths(gradleUserHome)
const primaryKey = await computeCacheKey()
core.saveState(PRIMARY_KEY_STATE, primaryKey)
// No "restoreKeys" is set, to start with a clear cache after dependency update
// See https://github.com/actions/setup-java/issues/269
try {
const restoredKey = await cache.restoreCache(cachePaths, primaryKey)
if (restoredKey) {
core.saveState(RESTORED_KEY_STATE, restoredKey)
core.info(`Basic caching restored from cache key: ${restoredKey}`)
} else {
core.info('Basic caching did not find an entry to restore. Will start with empty state.')
}
} catch (error) {
core.warning(`Basic caching failed to restore from cache: ${error}`)
}
}
async save(gradleUserHome: string, _buildResults: BuildResult[], cacheOptions: CacheOptions): Promise<string> {
if (cacheOptions.readOnly) {
const restoredKey = core.getState(RESTORED_KEY_STATE)
if (restoredKey) {
return `Basic caching was read-only. Restored from cache key \`${restoredKey}\`.`
}
return 'Basic caching was read-only. No cache entry was found to restore.'
}
const primaryKey = core.getState(PRIMARY_KEY_STATE)
const restoredKey = core.getState(RESTORED_KEY_STATE)
if (restoredKey === primaryKey) {
core.info(`Basic caching restored entry with key \`${primaryKey}\`. Save was skipped.`)
return `Basic caching restored entry with key \`${primaryKey}\`. Save was skipped.`
}
const cachePaths = getCachePaths(gradleUserHome)
try {
await cache.saveCache(cachePaths, primaryKey)
core.info(`Basic caching saved entry with key: ${primaryKey}`)
return `Basic caching saved entry with key \`${primaryKey}\`.`
} catch (error) {
core.warning(`Basic caching failed to save entry with key \`${primaryKey}\`: ${error}`)
return `Basic caching save failed: ${error}`
}
}
}
function getCachePaths(gradleUserHome: string): string[] {
return [path.join(gradleUserHome, 'caches'), path.join(gradleUserHome, 'wrapper')]
}
async function computeCacheKey(): Promise<string> {
const fileHash = await glob.hashFiles(GRADLE_BUILD_FILE_PATTERNS.join('\n'))
if (!fileHash) {
throw new Error(
`No file in ${process.cwd()} matched to [${GRADLE_BUILD_FILE_PATTERNS}], make sure you have checked out the target repository`
)
}
return `${CACHE_KEY_PREFIX}-${process.env['RUNNER_OS']}-${process.arch}-gradle-${fileHash}`
}
sources/src/cache-service-loader.ts
+31 -34
View File
@@ -2,7 +2,8 @@ import * as fs from 'fs'
import * as path from 'path'
import {pathToFileURL} from 'url'
import {CacheConfig} from './configuration'
import {CacheConfig, CacheProvider} from './configuration'
import {BasicCacheService} from './cache-service-basic'
import {BuildResult} from './build-results'
import {CacheOptions, CacheService} from './cache-service'
@@ -10,36 +11,24 @@ const NOOP_CACHING_REPORT = `
[Cache was disabled](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#disabling-caching). Gradle User Home was not restored from or saved to the cache.
`
const CACHE_LICENSE_WARNING = `
***********************************************************
LICENSING NOTICE
const ENHANCED_CACHE_MESSAGE = `Enhanced Caching: This build is using the proprietary 'gradle-actions-caching' provider for optimized caching support. See https://github.com/gradle/actions/blob/main/DISTRIBUTION.md for terms of use and opt-out instructions.`
The caching functionality in \`gradle-actions\` has been extracted into \`gradle-actions-caching\`, a proprietary commercial component that is not covered by the MIT License.
The bundled \`gradle-actions-caching\` component is licensed and governed by a separate license, available at https://gradle.com/legal/terms-of-use/.
The \`gradle-actions-caching\` component is used only when caching is enabled and is not loaded or used when caching is disabled.
Use of the \`gradle-actions-caching\` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
If you do not agree to these license terms, do not use the \`gradle-actions-caching\` component.
You can suppress this message by accepting the terms in your action configuration: see https://github.com/gradle/actions/blob/main/README.md
***********************************************************
const ENHANCED_CACHE_SUMMARY = `
> [!NOTE]
> ### ⚡️ Enhanced Caching enabled
> This build provides optimized caching support via the proprietary **gradle-actions-caching** provider.
> See [DISTRIBUTION.md](https://github.com/gradle/actions/blob/main/DISTRIBUTION.md) for terms of use and opt-out instructions.
`
const CACHE_LICENSE_SUMMARY = `
> [!IMPORTANT]
> #### Licensing notice
>
> The caching functionality in \`gradle-actions\` has been extracted into \`gradle-actions-caching\`, a proprietary commercial component that is not covered by the MIT License.
> The bundled \`gradle-actions-caching\` component is licensed and governed by a separate license, available at https://gradle.com/legal/terms-of-use/.
>
> The \`gradle-actions-caching\` component is used only when caching is enabled and is not loaded or used when caching is disabled.
>
> Use of the \`gradle-actions-caching\` component is subject to a separate license, available at https://gradle.com/legal/terms-of-use/.
> If you do not agree to these license terms, do not use the \`gradle-actions-caching\` component.
>
>You can suppress this message by [accepting the terms in your action configuration](https://github.com/gradle/actions/blob/main/README.md).
`
const BASIC_CACHE_MESSAGE = `Basic Caching: This build uses the open-source caching provider for reliable, path-based caching of Gradle dependencies. Upgrade available: for faster builds and advanced features, consider switching to the Enhanced Caching provider. See https://github.com/gradle/actions/blob/main/DISTRIBUTION.md for details.`
const BASIC_CACHE_SUMMARY = `
> [!NOTE]
> ### 🛡️ Basic Caching enabled
> This build uses the open-source caching provider for reliable, path-based caching of Gradle dependencies.
>
> **Upgrade Available:** For faster builds and advanced features, consider switching to the **Enhanced Caching** provider.
> See [DISTRIBUTION.md](https://github.com/gradle/actions/blob/main/DISTRIBUTION.md) for details.`
class NoOpCacheService implements CacheService {
async restore(_gradleUserHome: string, _cacheOptions: CacheOptions): Promise<void> {
@@ -53,9 +42,11 @@ class NoOpCacheService implements CacheService {
class LicenseWarningCacheService implements CacheService {
private delegate: CacheService
private summary: string
constructor(delegate: CacheService) {
constructor(delegate: CacheService, summary: string) {
this.delegate = delegate
this.summary = summary
}
async restore(gradleUserHome: string, cacheOptions: CacheOptions): Promise<void> {
@@ -64,22 +55,28 @@ class LicenseWarningCacheService implements CacheService {
async save(gradleUserHome: string, buildResults: BuildResult[], cacheOptions: CacheOptions): Promise<string> {
const cachingReport = await this.delegate.save(gradleUserHome, buildResults, cacheOptions)
return `${cachingReport}\n${CACHE_LICENSE_SUMMARY}`
return `${cachingReport}\n${this.summary}`
}
}
export async function getCacheService(cacheConfig: CacheConfig): Promise<CacheService> {
if (cacheConfig.isCacheDisabled()) {
logCacheMessage('Cache is disabled: will not restore state from previous builds.')
return new NoOpCacheService()
}
if (cacheConfig.getCacheProvider() === CacheProvider.Basic) {
logCacheMessage(BASIC_CACHE_MESSAGE)
return new LicenseWarningCacheService(new BasicCacheService(), BASIC_CACHE_SUMMARY)
}
logCacheMessage(ENHANCED_CACHE_MESSAGE)
const cacheService = await loadVendoredCacheService()
if (cacheConfig.isCacheLicenseAccepted()) {
return cacheService
}
await logCacheLicenseWarning()
return new LicenseWarningCacheService(cacheService)
return new LicenseWarningCacheService(cacheService, ENHANCED_CACHE_SUMMARY)
}
export async function loadVendoredCacheService(): Promise<CacheService> {
@@ -99,6 +96,6 @@ function findVendoredLibraryPath(): string {
throw new Error(`Unable to locate vendored cache library at ${absolutePath}.`)
}
export async function logCacheLicenseWarning(): Promise<void> {
console.info(CACHE_LICENSE_WARNING)
export function logCacheMessage(message: string): void {
console.info(message)
}
sources/src/configuration.ts
+17
View File
@@ -171,6 +171,23 @@ export class CacheConfig {
const dvConfig = new DevelocityConfig()
return dvConfig.getDevelocityAccessKey() !== '' || dvConfig.hasTermsOfUseAgreement()
}
getCacheProvider(): CacheProvider {
const val = core.getInput('cache-provider')
switch (val.toLowerCase().trim()) {
case 'basic':
return CacheProvider.Basic
case 'enhanced':
case '':
return CacheProvider.Enhanced
}
throw TypeError(`The value '${val}' is not valid for 'cache-provider'. Valid values are: [basic, enhanced].`)
}
}
export enum CacheProvider {
Basic = 'basic',
Enhanced = 'enhanced'
}
export enum CacheCleanupOption {
sources/test/jest/cache-service-basic.test.ts
+234
View File
@@ -0,0 +1,234 @@
import {describe, expect, it, jest, beforeEach} from '@jest/globals'
// Mock @actions/cache
const mockRestoreCache = jest.fn<(paths: string[], primaryKey: string, restoreKeys?: string[]) => Promise<string | undefined>>()
const mockSaveCache = jest.fn<(paths: string[], key: string) => Promise<number>>()
jest.unstable_mockModule('@actions/cache', () => ({
restoreCache: mockRestoreCache,
saveCache: mockSaveCache
}))
// Mock @actions/core
const mockInfo = jest.fn<(message: string) => void>()
const mockWarning = jest.fn<(message: string) => void>()
const mockSaveState = jest.fn<(name: string, value: string) => void>()
const mockGetState = jest.fn<(name: string) => string>()
jest.unstable_mockModule('@actions/core', () => ({
info: mockInfo,
warning: mockWarning,
saveState: mockSaveState,
getState: mockGetState
}))
// Mock @actions/glob
const mockHashFiles = jest.fn<(pattern: string) => Promise<string>>()
jest.unstable_mockModule('@actions/glob', () => ({
hashFiles: mockHashFiles
}))
const {BasicCacheService} = await import('../../src/cache-service-basic')
const HASH = 'abc123def456'
const PRIMARY_KEY = `setup-java-Linux-${process.arch}-gradle-${HASH}`
describe('BasicCacheService', () => {
let service: InstanceType<typeof BasicCacheService>
beforeEach(() => {
jest.clearAllMocks()
service = new BasicCacheService()
process.env['RUNNER_OS'] = 'Linux'
mockHashFiles.mockResolvedValue(HASH)
})
describe('restore', () => {
it('restores cache without restoreKeys and saves both keys to state', async () => {
mockRestoreCache.mockResolvedValue(PRIMARY_KEY)
await service.restore('/home/.gradle', {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
// No restoreKeys parameter — exact match only (setup-java#269)
expect(mockRestoreCache).toHaveBeenCalledWith(
['/home/.gradle/caches', '/home/.gradle/wrapper'],
PRIMARY_KEY
)
expect(mockSaveState).toHaveBeenCalledWith('BASIC_CACHE_PRIMARY_KEY', PRIMARY_KEY)
expect(mockSaveState).toHaveBeenCalledWith('BASIC_CACHE_RESTORED_KEY', PRIMARY_KEY)
})
it('saves primary key to state even on cache miss', async () => {
mockRestoreCache.mockResolvedValue(undefined)
await service.restore('/home/.gradle', {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockSaveState).toHaveBeenCalledWith('BASIC_CACHE_PRIMARY_KEY', PRIMARY_KEY)
expect(mockSaveState).not.toHaveBeenCalledWith('BASIC_CACHE_RESTORED_KEY', expect.anything())
expect(mockInfo).toHaveBeenCalledWith(
expect.stringContaining('did not find')
)
})
it('warns on restore failure instead of throwing', async () => {
mockRestoreCache.mockRejectedValue(new Error('Network error'))
await service.restore('/home/.gradle', {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockWarning).toHaveBeenCalledWith(
expect.stringContaining('failed to restore')
)
})
it('throws when no build files are found', async () => {
mockHashFiles.mockResolvedValue('')
await expect(
service.restore('/home/.gradle', {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
).rejects.toThrow('No file in')
})
})
describe('save', () => {
it('reports readOnly with restored key when cache was hit', async () => {
mockGetState.mockReturnValue(PRIMARY_KEY)
const report = await service.save('/home/.gradle', [], {
disabled: false,
readOnly: true,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockSaveCache).not.toHaveBeenCalled()
expect(report).toContain('read-only')
expect(report).toContain(PRIMARY_KEY)
})
it('reports readOnly with no restore when cache was missed', async () => {
mockGetState.mockReturnValue('')
const report = await service.save('/home/.gradle', [], {
disabled: false,
readOnly: true,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockSaveCache).not.toHaveBeenCalled()
expect(report).toContain('read-only')
expect(report).toContain('No cache entry')
})
it('skips save when restored key equals primary key', async () => {
mockGetState.mockImplementation((name: string) => {
if (name === 'BASIC_CACHE_PRIMARY_KEY') return PRIMARY_KEY
if (name === 'BASIC_CACHE_RESTORED_KEY') return PRIMARY_KEY
return ''
})
const report = await service.save('/home/.gradle', [], {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockSaveCache).not.toHaveBeenCalled()
expect(report).toContain('Save was skipped')
})
it('saves cache and returns report on success', async () => {
mockGetState.mockImplementation((name: string) => {
if (name === 'BASIC_CACHE_PRIMARY_KEY') return PRIMARY_KEY
return ''
})
mockSaveCache.mockResolvedValue(0)
const report = await service.save('/home/.gradle', [], {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockSaveCache).toHaveBeenCalledWith(
['/home/.gradle/caches', '/home/.gradle/wrapper'],
PRIMARY_KEY
)
expect(report).toContain('saved entry with key')
})
it('warns on save failure instead of throwing', async () => {
mockGetState.mockImplementation((name: string) => {
if (name === 'BASIC_CACHE_PRIMARY_KEY') return PRIMARY_KEY
return ''
})
mockSaveCache.mockRejectedValue(new Error('Storage full'))
const report = await service.save('/home/.gradle', [], {
disabled: false,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
expect(mockWarning).toHaveBeenCalledWith(
expect.stringContaining('failed to save')
)
expect(report).toContain('failed')
})
})
})
sources/test/jest/cache-service-loader.test.ts
+50
View File
@@ -0,0 +1,50 @@
import {describe, expect, it, jest, beforeEach} from '@jest/globals'
import {CacheProvider} from '../../src/configuration'
import type {CacheConfig} from '../../src/configuration'
describe('getCacheService selection logic', () => {
beforeEach(() => {
jest.restoreAllMocks()
})
it('returns NoOpCacheService when cache is disabled', async () => {
const {getCacheService} = await import('../../src/cache-service-loader')
const mockConfig = {
isCacheDisabled: () => true,
getCacheProvider: () => CacheProvider.Enhanced,
isCacheLicenseAccepted: () => true
} as unknown as CacheConfig
const service = await getCacheService(mockConfig)
const report = await service.save('/home/.gradle', [], {
disabled: true,
readOnly: false,
writeOnly: false,
overwriteExisting: false,
strictMatch: false,
cleanup: 'never',
includes: [],
excludes: []
})
// NoOpCacheService returns a specific report mentioning cache was disabled
expect(report).toContain('Cache was disabled')
})
it('wraps BasicCacheService with LicenseWarningCacheService when cache-provider is basic', async () => {
const {getCacheService} = await import('../../src/cache-service-loader')
const mockConfig = {
isCacheDisabled: () => false,
getCacheProvider: () => CacheProvider.Basic,
isCacheLicenseAccepted: () => false
} as unknown as CacheConfig
const service = await getCacheService(mockConfig)
// The service should not be a bare BasicCacheService — it should be wrapped
// with LicenseWarningCacheService that appends the basic caching summary
const {BasicCacheService} = await import('../../src/cache-service-basic')
expect(service).not.toBeInstanceOf(BasicCacheService)
})
})