Allow better control over cache-cleanup

Adds new 'cache-cleanup' parameter with 3 settings: 'never', 'on-success' and 'always'.
This gives users more control over whether cache cleanup should occur.

Fixes #71

.github/workflows/demo-job-summary.yml

@@ -23,6 +23,9 @@ jobs:
 
     - name: Setup Gradle
       uses: ./setup-gradle
+      with:
+        cache-read-only: false
+        cache-cleanup: 'on-success'
     - name: Build kotlin-dsl project
       working-directory: .github/workflow-samples/kotlin-dsl
       run: ./gradlew assemble

dependency-submission/action.yml

@@ -57,6 +57,20 @@ inputs:
       Configuration-cache data will not be saved/restored without an encryption key being provided.
     required: false
 
+  cache-cleanup:
+    description: |
+      Specifies if the action should attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
+      By default, no cleanup is performed. It can be configured to run every time, or only when all Gradle builds succeed for the Job. 
+      Valid values are 'never', 'on-success' and 'always'.
+    required: false
+    default: 'never'
+
+  gradle-home-cache-cleanup:
+    description: When 'true', the action will attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
+    required: false
+    default: false
+    deprecation-message: This input has been superceded by the 'cache-cleanup' input parameter.
+
   gradle-home-cache-includes:
     description: Paths within Gradle User Home to cache.
     required: false
@@ -68,11 +82,6 @@ inputs:
     description: Paths within Gradle User Home to exclude from cache.
     required: false
 
-  gradle-home-cache-cleanup:
-    description: When 'true', the action will attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
-    required: false
-    default: false
-
   # Job summary configuration
   add-job-summary:
     description: Specifies when a Job Summary should be inluded in the action results. Valid values are 'never', 'always' (default), and 'on-failure'.

docs/setup-gradle.md

@@ -153,6 +153,23 @@ In certain circumstances it may be desirable to start with a clean Gradle User H
 cache-write-only: true
 ```
 
+### Enabling cache cleanup
+
+The Gradle User Home directory tends to grow over time. When you switch to a new Gradle wrapper version or upgrade a dependency version
+the old files are not automatically and immediately removed. While this can make sense in a local environment, in a GitHub Actions environment
+it can lead to ever-larger Gradle User Home cache entries being saved and restored.
+
+To avoid this situation, The `setup-gradle` action supports the `cache-cleanup` parameter.
+When cache-cleanup is enabled, this feature will attempt to delete any files in the Gradle User Home that were not used by Gradle during the GitHub Actions Workflow, before saving the Gradle User Home to the GitHub Actions cache.
+
+If cache cleanup runs after a failing Gradle build, it is possible that some required files and dependencies will not be touched, and will be removed.
+To prevent this scenario, cache cleanup can be configured to run only when all Gradle builds in the Job are successful.
+
+Gradle Home cache cleanup is considered experimental and is disabled by default.  You can enable this feature for the action as follows:
+```yaml
+cache-cleanup: 'on-success' # Valid values are 'never' (default), 'on-success' and 'always'
+```
+
 ### Overwriting an existing Gradle User Home
 
 When the action detects that the Gradle User Home caches directory already exists (`~/.gradle/caches`), then by default it will not overwrite the existing content of this directory.
@@ -362,13 +379,7 @@ The Gradle User Home directory tends to grow over time. When you switch to a new
 the old files are not automatically and immediately removed. While this can make sense in a local environment, in a GitHub Actions environment
 it can lead to ever-larger Gradle User Home cache entries being saved and restored.
 
-To avoid this situation, The `setup-gradle` action supports the `gradle-home-cache-cleanup` parameter.
-When enabled, this feature will attempt to delete any files in the Gradle User Home that were not used by Gradle during the GitHub Actions Workflow, before saving the Gradle User Home to the GitHub Actions cache.
-
-Gradle Home cache cleanup is considered experimental and is disabled by default.  You can enable this feature for the action as follows:
-```yaml
-gradle-home-cache-cleanup: true
-```
+See [Enabling cache cleanup](#enabling-cache-cleanup) for a mechanism to mitigate this problem.
 
 ### Disable local build-cache when remote build-cache is available
 

setup-gradle/action.yml

@@ -40,6 +40,20 @@ inputs:
       Configuration-cache data will not be saved/restored without an encryption key being provided.
     required: false
 
+  cache-cleanup:
+    description: |
+      Specifies if the action should attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
+      By default, no cleanup is performed. It can be configured to run every time, or only when all Gradle builds succeed for the Job. 
+      Valid values are 'never', 'on-success' and 'always'.
+    required: false
+    default: 'never'
+
+  gradle-home-cache-cleanup:
+    description: When 'true', the action will attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
+    required: false
+    default: false
+    deprecation-message: This input has been superceded by the 'cache-cleanup' input parameter.
+
   gradle-home-cache-includes:
     description: Paths within Gradle User Home to cache.
     required: false
@@ -51,11 +65,6 @@ inputs:
     description: Paths within Gradle User Home to exclude from cache.
     required: false
 
-  gradle-home-cache-cleanup:
-    description: When 'true', the action will attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
-    required: false
-    default: false
-
   # Job summary configuration
   add-job-summary:
     description: Specifies when a Job Summary should be inluded in the action results. Valid values are 'never', 'always' (default), and 'on-failure'.

sources/src/caching/cache-reporting.ts

@@ -10,9 +10,14 @@ export const DEFAULT_WRITEONLY_REASON = `[Cache was set to write-only](https://g
 
 export const EXISTING_GRADLE_HOME = `[Cache was disabled to avoid overwriting a pre-existing Gradle User Home](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#overwriting-an-existing-gradle-user-home). Gradle User Home was not restored from or saved to the cache.`
 
-export const DEFAULT_CLEANUP_DISABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#remove-unused-files-from-gradle-user-home-before-saving-to-the-cache) was not enabled. It must be explicitly enabled.`
+export const CLEANUP_DISABLED_READONLY = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup) is always disabled when cache is read-only or disabled.`
 
-export const DEFAULT_CLEANUP_ENABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#remove-unused-files-from-gradle-user-home-before-saving-to-the-cache) was enabled.`
+export const DEFAULT_CLEANUP_DISABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup) was not enabled. It must be explicitly enabled.`
+
+export const DEFAULT_CLEANUP_ENABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup) was enabled.`
+
+export const CLEANUP_DISABLED_DUE_TO_FAILURE =
+    '[Cache cleanup was disabled due to build failure](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup). Use `cache-cleanup: always` to override this behavior.'
 
 /**
  * Collects information on what entries were saved and restored during the action.
@@ -41,11 +46,13 @@ export class CacheListener {
     setReadOnly(reason: string = DEFAULT_READONLY_REASON): void {
         this.cacheReadOnly = true
         this.cacheStatusReason = reason
+        this.cacheCleanupMessage = CLEANUP_DISABLED_READONLY
     }
 
     setDisabled(reason: string = DEFAULT_DISABLED_REASON): void {
         this.cacheDisabled = true
         this.cacheStatusReason = reason
+        this.cacheCleanupMessage = CLEANUP_DISABLED_READONLY
     }
 
     setWriteOnly(reason: string = DEFAULT_WRITEONLY_REASON): void {
@@ -57,6 +64,10 @@ export class CacheListener {
         this.cacheCleanupMessage = DEFAULT_CLEANUP_ENABLED_REASON
     }
 
+    setCacheCleanupDisabled(reason: string = DEFAULT_CLEANUP_DISABLED_REASON): void {
+        this.cacheCleanupMessage = reason
+    }
+
     entry(name: string): CacheEntryListener {
         for (const entry of this.cacheEntries) {
             if (entry.entryName === name) {

sources/src/caching/caches.ts

@@ -1,9 +1,10 @@
 import * as core from '@actions/core'
-import {CacheListener, EXISTING_GRADLE_HOME} from './cache-reporting'
+import {CacheListener, EXISTING_GRADLE_HOME, CLEANUP_DISABLED_DUE_TO_FAILURE} from './cache-reporting'
 import {GradleUserHomeCache} from './gradle-user-home-cache'
 import {CacheCleaner} from './cache-cleaner'
 import {DaemonController} from '../daemon-controller'
 import {CacheConfig} from '../configuration'
+import {BuildResults} from '../build-results'
 
 const CACHE_RESTORED_VAR = 'GRADLE_BUILD_ACTION_CACHE_RESTORED'
 
@@ -67,6 +68,7 @@ export async function save(
     gradleUserHome: string,
     cacheListener: CacheListener,
     daemonController: DaemonController,
+    buildResults: BuildResults,
     cacheConfig: CacheConfig
 ): Promise<void> {
     if (cacheConfig.isCacheDisabled()) {
@@ -88,13 +90,12 @@ export async function save(
     await daemonController.stopAllDaemons()
 
     if (cacheConfig.isCacheCleanupEnabled()) {
-        cacheListener.setCacheCleanupEnabled()
-        core.info('Forcing cache cleanup.')
-        const cacheCleaner = new CacheCleaner(gradleUserHome, process.env['RUNNER_TEMP']!)
-        try {
-            await cacheCleaner.forceCleanup()
-        } catch (e) {
-            core.warning(`Cache cleanup failed. Will continue. ${String(e)}`)
+        if (cacheConfig.shouldPerformCacheCleanup(buildResults.anyFailed())) {
+            cacheListener.setCacheCleanupEnabled()
+            await performCacheCleanup(gradleUserHome)
+        } else {
+            core.info('Not performing cache-cleanup due to build failure')
+            cacheListener.setCacheCleanupDisabled(CLEANUP_DISABLED_DUE_TO_FAILURE)
         }
     }
 
@@ -102,3 +103,13 @@ export async function save(
         return new GradleUserHomeCache(userHome, gradleUserHome, cacheConfig).save(cacheListener)
     })
 }
+
+async function performCacheCleanup(gradleUserHome: string): Promise<void> {
+    core.info('Forcing cache cleanup.')
+    const cacheCleaner = new CacheCleaner(gradleUserHome, process.env['RUNNER_TEMP']!)
+    try {
+        await cacheCleaner.forceCleanup()
+    } catch (e) {
+        core.warning(`Cache cleanup failed. Will continue. ${String(e)}`)
+    }
+}

sources/src/configuration.ts

@@ -111,7 +111,40 @@ export class CacheConfig {
     }
 
     isCacheCleanupEnabled(): boolean {
-        return getBooleanInput('gradle-home-cache-cleanup') && !this.isCacheReadOnly()
+        if (this.isCacheReadOnly()) {
+            return false
+        }
+        const cleanupOption = this.getCacheCleanupOption()
+        return cleanupOption === CacheCleanupOption.Always || cleanupOption === CacheCleanupOption.OnSuccess
+    }
+
+    shouldPerformCacheCleanup(hasFailure: boolean): boolean {
+        const cleanupOption = this.getCacheCleanupOption()
+        if (cleanupOption === CacheCleanupOption.Always) {
+            return true
+        }
+        if (cleanupOption === CacheCleanupOption.OnSuccess) {
+            return !hasFailure
+        }
+        return false
+    }
+
+    private getCacheCleanupOption(): CacheCleanupOption {
+        const val = core.getInput('cache-cleanup')
+        switch (val.toLowerCase().trim()) {
+            case 'always':
+                return CacheCleanupOption.Always
+            case 'on-success':
+                return CacheCleanupOption.OnSuccess
+            case 'never':
+                // When set to 'never' (the default), honour the legacy parameter setting.
+                return getBooleanInput('gradle-home-cache-cleanup')
+                    ? CacheCleanupOption.Always
+                    : CacheCleanupOption.Never
+        }
+        throw TypeError(
+            `The value '${val}' is not valid for cache-cleanup. Valid values are: [never, always, on-success].`
+        )
     }
 
     getCacheEncryptionKey(): string {
@@ -127,6 +160,12 @@ export class CacheConfig {
     }
 }
 
+export enum CacheCleanupOption {
+    Never = 'never',
+    OnSuccess = 'on-success',
+    Always = 'always'
+}
+
 export class SummaryConfig {
     shouldGenerateJobSummary(hasFailure: boolean): boolean {
         // Check if Job Summary is supported on this platform

sources/src/setup-gradle.ts

@@ -60,7 +60,7 @@ export async function complete(cacheConfig: CacheConfig, summaryConfig: SummaryC
     const cacheListener: CacheListener = CacheListener.rehydrate(core.getState(CACHE_LISTENER))
 
     const daemonController = new DaemonController(buildResults)
-    await caches.save(userHome, gradleUserHome, cacheListener, daemonController, cacheConfig)
+    await caches.save(userHome, gradleUserHome, cacheListener, daemonController, buildResults, cacheConfig)
 
     const cachingReport = generateCachingReport(cacheListener)
     await jobSummary.generateJobSummary(buildResults, cachingReport, summaryConfig)