Merge pull request #101 from gradle/dd/rename-parameters

Rename and document parameters for clarity 

- cache-paths -> gradle-home-cache-includes
- cache-exclude-paths -> gradle-home-cache-excludes
- CACHE_DEBUG_ENABLED -> GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED

.github/workflows/failure-cases.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:
 

.github/workflows/integTest-action-inputs.yml

@@ -0,0 +1,30 @@
+name: Test different action inputs
+
+on:
+  pull_request:
+  push:
+  workflow_dispatch:
+
+env:
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+
+jobs:
+  action-inputs:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Checkout sources
+      uses: actions/checkout@v2
+    - name: Invoke with multi-line arguments
+      uses: ./
+      with:
+        build-root-directory: __tests__/samples/groovy-dsl
+        arguments: |
+            --configuration-cache
+            --build-cache
+            -DsystemProperty=FOO
+            -PgradleProperty=BAR
+            test
+            jar

.github/workflows/integTest-caching-config.yml

@@ -0,0 +1,71 @@
+name: Test caching configuration
+
+on:
+  pull_request:
+  push:
+  workflow_dispatch:
+
+env:
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
+
+jobs:
+  # Run initial Gradle builds to push initial cache entries
+  # These builds should start fresh without cache hits, due to the seed injected into the cache key above.
+  seed-build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Checkout sources
+      uses: actions/checkout@v2
+    - name: Build using Gradle wrapper
+      uses: ./
+      with:
+        build-root-directory: __tests__/samples/groovy-dsl
+        arguments: test
+        # Add "wrapper" to main cache entry and remove 'wrapper-zips' bundle
+        # Exclude build-cache from main cache entry
+        gradle-home-cache-includes: |
+            ["caches", "notifications", "wrapper"]
+        gradle-home-cache-excludes: |
+            ["caches/build-cache-1"]
+        gradle-home-cache-artifact-bundles: |
+            [
+              ["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
+              ["dependency-jars", "caches/modules-*/files-*/**/*.jar"],
+              ["instrumented-jars", "caches/jars-*/*/"],
+              ["kotlin-dsl", "caches/*/kotlin-dsl/*/*/"]
+            ]
+
+  # Test that the gradle-user-home cache will cache dependencies, by running build with --offline
+  verify-build:
+    needs: seed-build
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Checkout sources
+      uses: actions/checkout@v2
+    - name: Execute Gradle build with --offline
+      uses: ./
+      with:
+        build-root-directory: __tests__/samples/groovy-dsl
+        arguments: test --offline
+        cache-read-only: true
+        # Need the same configuration when restoring state from cache
+        gradle-home-cache-includes: |
+            ["caches", "notifications", "wrapper"]
+        gradle-home-cache-excludes: |
+            ["caches/build-cache-1"]
+        gradle-home-cache-artifact-bundles: |
+            [
+              ["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
+              ["dependency-jars", "caches/modules-*/files-*/**/*.jar"],
+              ["instrumented-jars", "caches/jars-*/*/"],
+              ["kotlin-dsl", "caches/*/kotlin-dsl/*/*/"]
+            ]
+
+

.github/workflows/integTest-caching.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:
   # Run initial Gradle builds to push initial cache entries
@@ -14,7 +14,7 @@ jobs:
   seed-build:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
@@ -35,7 +35,7 @@ jobs:
     needs: seed-build
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
@@ -52,7 +52,7 @@ jobs:
     needs: seed-build
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
@@ -69,7 +69,7 @@ jobs:
     needs: seed-build
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
@@ -82,3 +82,22 @@ jobs:
         build-root-directory: __tests__/samples/groovy-dsl
         arguments: test --configuration-cache
         cache-read-only: true
+
+  # Check that the build can run when no bundles are restored
+  no-bundles-restored:
+    needs: seed-build
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - name: Checkout sources
+      uses: actions/checkout@v2
+    - name: Execute Gradle build with no cache artifact bundles restored
+      uses: ./
+      with:
+        build-root-directory: __tests__/samples/groovy-dsl
+        arguments: test
+        cache-read-only: true
+        gradle-home-cache-artifact-bundles: '[]'
+

.github/workflows/integTest-execution.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:   
   # Tests for executing with different Gradle versions. 
@@ -14,7 +14,7 @@ jobs:
   gradle-execution:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
         include:
           - os: windows-latest
             script-suffix: '.bat'
@@ -33,7 +33,7 @@ jobs:
       with:
         gradle-version: release-candidate
         build-root-directory: __tests__/samples/no-wrapper
-        arguments: help -DgradleVersionCheck=7.2
+        arguments: help
     - name: Test use defined Gradle executable
       uses: ./
       with:
@@ -44,7 +44,7 @@ jobs:
   gradle-versions:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest]
         include:
           - os: windows-latest
             script-suffix: '.bat'

.github/workflows/integTest-gradle-user-home.yml

@@ -6,14 +6,17 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
   GRADLE_USER_HOME: custom/gradle/home
 
 jobs:
   # Run initial Gradle builds to push initial cache entries
   # These builds should start fresh without cache hits, due to the seed injected into the cache key above.
   seed-build:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
       uses: actions/checkout@v2
@@ -26,7 +29,10 @@ jobs:
   # Test that the gradle-user-home cache will cache dependencies, by running build with --offline
   dependencies-cache:
     needs: seed-build
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
       uses: actions/checkout@v2
@@ -40,7 +46,10 @@ jobs:
   # Test that the gradle-user-home cache will cache and restore local build-cache
   build-cache:
     needs: seed-build
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
       uses: actions/checkout@v2

.github/workflows/integTest-kotlin-dsl.yml

@@ -6,13 +6,16 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
-  CACHE_DEBUG_ENABLED: true
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
 
 jobs:
   # Use kotlin-dsl project to verify caching of generated jars and compiled scripts
   seed-build:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
       uses: actions/checkout@v2
@@ -25,7 +28,10 @@ jobs:
   # Check that the build can run --offline
   verify-build:
     needs: seed-build
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
     - name: Checkout sources
       uses: actions/checkout@v2

README.md

@@ -47,6 +47,7 @@ Each invocation will start its run with the filesystem state remaining from the
 ### Command-line arguments
 
 The `arguments` input can used to pass arbitrary arguments to the `gradle` command line.
+Arguments can be supplied in a single line, or as a multi-line input.
 
 Here are some valid examples:
 ```yaml
@@ -54,8 +55,11 @@ arguments: build
 arguments: check --scan
 arguments: some arbitrary tasks
 arguments: build -PgradleProperty=foo
-arguments: build -DsystemProperty=bar
-....
+arguments: |
+    build
+    --scan
+    -PgradleProperty=foo
+    -DsystemProperty=bar
 ```
 
 See `gradle --help` for more information.
@@ -155,12 +159,9 @@ Caching is enabled by default. You can disable caching for the action as follows
 cache-disabled: true
 ```
 
-At this time it is not possible to fine-tune the caching performed by this action. 
-If you have a legitimate use case for fine-grained caching or restricting which files are cached, please raise an issue.
-
 ### Cache keys
 
-For cached distributions, the cache key is unique to the downloaded distribution. This will not change over time.
+For cached distributions outside of Gradle User Home, the cache key is unique to the downloaded distribution. This will not change over time.
 
 The state of the Gradle User Home and configuration-cache are highly dependent on the Gradle execution, so the cache key is composed of the current commit hash and the GitHub actions job id.
 As such, the cache key is likely to change on each subsequent run of GitHub actions. 
@@ -179,9 +180,40 @@ For example, you may want to write cache entries for builds on your `main` branc
 You can enable read-only caching for any of the caches as follows:
 
 ```yaml
-cache-read-only: true
+# Only write to the cache for builds on the 'main' branch.
+# Builds on other branches will only read existing entries from the cache.
+cache-read-only: ${{ github.ref != 'refs/heads/main' }}
 ```
 
+### Gradle User Home cache tuning
+
+As well as any wrapper distributions, the action will attempt to save and restore the `caches` and `notifications` directories from Gradle User Home.
+
+The contents to be cached can be fine tuned by including and excluding certain paths with Gradle User Home.
+
+```yaml
+# Cache downloaded JDKs in addition to the default directories.
+gradle-home-cache-includes: |
+    ["caches", "notifications", "jdks"]
+# Exclude the local build-cache from the directories cached.
+gradle-home-cache-excludes: |
+    ["caches/build-cache-1"]
+```
+
+You can specify any number of fixed paths or patterns to include or exclude. 
+File pattern support is documented at https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#patterns-to-match-file-paths.
+
+### Cache debugging
+
+It is possible to enable additional debug logging for cache operations. You do via the `GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED` environment variable:
+
+```yaml
+env:
+  GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
+```
+
+Note that this setting will also prevent certain cache operations from running in parallel, further assisting with debugging.
+
 ## Build scans
 
 If your build publishes a [build scan](https://gradle.com/build-scans/) the `gradle-build-action` action will:

action.yml

@@ -7,29 +7,65 @@ inputs:
   gradle-executable:
     description: Path to the Gradle executable
     required: false
+
   gradle-version:
     description: Gradle version to use
     required: false
+
   build-root-directory:
     description: Path to the root directory of the build
     required: false
+
   arguments:
-    description: Gradle command line arguments, see gradle --help
+    description: Gradle command line arguments (supports multi-line input)
     required: false
+
   cache-disabled:
     description: When 'true', all caching is disabled. No entries will be written to or read from the cache.
     required: false
     default: false
-  cache-read-only:
-    description: When 'true', existing entries will be read from the cache but no entries will be written
-    required: false
-    # TODO: It might be useful to default to read-only for PRs, or non-main branch.
-    default: false 
 
+  cache-read-only:
+    description: When 'true', existing entries will be read from the cache but no entries will be written.
+    required: false
+    default: false 
+  # e.g. Use the following setting to only write cache entries from your 'main' branch
+  #     cache-read-only: ${{ github.ref != 'refs/heads/main' }}
+
+  gradle-home-cache-includes:
+    description: Paths within Gradle User Home to cache.
+    required: false
+    default: |
+        ["caches", "notifications"]
+
+  gradle-home-cache-excludes:
+    description: Paths within Gradle User Home to exclude from cache.
+    required: false
+    default: |
+        [] 
+  # e.g. Use the following setting to prevent the local build cache from being saved/restored
+  #      gradle-home-cache-excludes: |
+  #           ["caches/build-cache-1"]
+
+  # EXPERIMENTAL & INTERNAL CONFIGURATION PROPERTIES
+  # The following action properties allow fine-grained tweaking of the action caching behaviour.
+  # These properties are not designed for production use, and may change without notice in a subsequent release of `gradle-build-action`.
+  # Use at your own risk!
   workflow-job-context:
-    description: Used to uniquely identify the current job invocation. Defaults to the matrix values for this job; this should not be overridden by users.
+    description: Used to uniquely identify the current job invocation. Defaults to the matrix values for this job; this should not be overridden by users (INTERNAL).
     required: false
     default: ${{ toJSON(matrix) }}
+  gradle-home-cache-artifact-bundles:
+    description: Names and patterns of artifact bundles to cache separately. (EXPERIMENTAL - may be changed/removed without notice)
+    required: false
+    default: |
+        [
+          ["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
+          ["wrapper-zips", "wrapper/dists/*/*/*.zip"],
+          ["dependency-jars", "caches/modules-*/files-*/**/*.jar"],
+          ["instrumented-jars", "caches/jars-*/*/"],
+          ["kotlin-dsl", "caches/*/kotlin-dsl/*/*/"]
+        ]
 
 outputs:
   build-scan-url:

src/cache-gradle-user-home.ts

@@ -5,17 +5,18 @@ import * as core from '@actions/core'
 import * as glob from '@actions/glob'
 import * as exec from '@actions/exec'
 
-import {AbstractCache, hashFileNames, tryDelete} from './cache-utils'
+import {
+    AbstractCache,
+    getCacheKeyPrefix,
+    hashFileNames,
+    tryDelete
+} from './cache-utils'
 
-// Which paths under Gradle User Home should be cached
-const CACHE_PATH = ['caches', 'notifications']
+const META_FILE_DIR = '.gradle-build-action'
 
-const COMMON_ARTIFACT_CACHES = new Map([
-    ['generated-gradle-jars', 'caches/*/generated-gradle-jars/*.jar'],
-    ['wrapper-zips', 'wrapper/dists/*/*/*.zip'],
-    ['dependency-jars', 'caches/modules-*/files-*/**/*.jar'],
-    ['instrumented-jars', 'caches/jars-*/*/*.jar']
-])
+const INCLUDE_PATHS_PARAMETER = 'gradle-home-cache-includes'
+const EXCLUDE_PATHS_PARAMETER = 'gradle-home-cache-excludes'
+const ARTIFACT_BUNDLES_PARAMETER = 'gradle-home-cache-artifact-bundles'
 
 export class GradleUserHomeCache extends AbstractCache {
     private gradleUserHome: string
@@ -26,15 +27,15 @@ export class GradleUserHomeCache extends AbstractCache {
     }
 
     async afterRestore(): Promise<void> {
-        await this.reportCacheEntrySize('as restored from cache')
-        await this.restoreCommonArtifacts()
-        await this.reportCacheEntrySize('after restoring common artifacts')
+        await this.reportGradleUserHomeSize('as restored from cache')
+        await this.restoreArtifactBundles()
+        await this.reportGradleUserHomeSize('after restoring common artifacts')
     }
 
-    private async restoreCommonArtifacts(): Promise<void> {
+    private async restoreArtifactBundles(): Promise<void> {
         const processes: Promise<void>[] = []
-        for (const [bundle, pattern] of this.getCommonArtifactPaths()) {
-            const p = this.restoreCommonArtifactBundle(bundle, pattern)
+        for (const [bundle, pattern] of this.getArtifactBundles()) {
+            const p = this.restoreArtifactBundle(bundle, pattern)
             // Run sequentially when debugging enabled
             if (this.cacheDebuggingEnabled) {
                 await p
@@ -45,13 +46,13 @@ export class GradleUserHomeCache extends AbstractCache {
         await Promise.all(processes)
     }
 
-    private async restoreCommonArtifactBundle(
+    private async restoreArtifactBundle(
         bundle: string,
         artifactPath: string
     ): Promise<void> {
-        const cacheMetaFile = this.getCacheMetaFile(bundle)
-        if (fs.existsSync(cacheMetaFile)) {
-            const cacheKey = fs.readFileSync(cacheMetaFile, 'utf-8').trim()
+        const bundleMetaFile = this.getBundleMetaFile(bundle)
+        if (fs.existsSync(bundleMetaFile)) {
+            const cacheKey = fs.readFileSync(bundleMetaFile, 'utf-8').trim()
             const restoreKey = await this.restoreCache([artifactPath], cacheKey)
             if (restoreKey) {
                 core.info(
@@ -59,65 +60,47 @@ export class GradleUserHomeCache extends AbstractCache {
                 )
             } else {
                 this.debug(
-                    `Failed to restore ${bundle} with key ${cacheKey} to ${artifactPath}`
+                    `Did not restore ${bundle} with key ${cacheKey} to ${artifactPath}`
                 )
             }
         } else {
             this.debug(
-                `No metafile found to restore ${bundle}: ${cacheMetaFile}`
+                `No metafile found to restore ${bundle}: ${bundleMetaFile}`
             )
         }
     }
 
-    private getCacheMetaFile(name: string): string {
-        return path.resolve(
-            this.gradleUserHome,
-            'caches',
-            `.gradle-build-action.${name}.cache`
-        )
-    }
-
-    private async reportCacheEntrySize(label: string): Promise<void> {
-        if (!this.cacheDebuggingEnabled) {
-            return
-        }
-        if (!fs.existsSync(this.gradleUserHome)) {
-            return
-        }
-        const result = await exec.getExecOutput(
-            'du',
-            ['-h', '-c', '-t', '5M'],
-            {
-                cwd: this.gradleUserHome,
-                silent: true,
-                ignoreReturnCode: true
-            }
-        )
-
-        core.info(`Gradle User Home cache entry (directories >5M): ${label}`)
-
-        core.info(
-            result.stdout
-                .trimEnd()
-                .replace(/\t/g, '    ')
-                .split('\n')
-                .map(it => {
-                    return `  ${it}`
-                })
-                .join('\n')
-        )
-
-        core.info('-----------------------')
+    private getBundleMetaFile(name: string): string {
+        return path.resolve(this.gradleUserHome, META_FILE_DIR, `${name}.cache`)
     }
 
     async beforeSave(): Promise<void> {
-        await this.saveCommonArtifacts()
+        await this.reportGradleUserHomeSize('before saving common artifacts')
+        this.removeExcludedPaths()
+        await this.saveArtifactBundles()
+        await this.reportGradleUserHomeSize(
+            "after saving common artifacts (only 'caches' and 'notifications' will be stored)"
+        )
     }
 
-    private async saveCommonArtifacts(): Promise<void> {
+    private removeExcludedPaths(): void {
+        const rawPaths: string[] = JSON.parse(
+            core.getInput(EXCLUDE_PATHS_PARAMETER)
+        )
+        const resolvedPaths = rawPaths.map(x =>
+            path.resolve(this.gradleUserHome, x)
+        )
+
+        for (const p of resolvedPaths) {
+            this.debug(`Deleting excluded path: ${p}`)
+            tryDelete(p)
+        }
+    }
+
+    private async saveArtifactBundles(): Promise<void> {
         const processes: Promise<void>[] = []
-        for (const [bundle, pattern] of this.getCommonArtifactPaths()) {
-            const p = this.saveCommonArtifactBundle(bundle, pattern)
+        for (const [bundle, pattern] of this.getArtifactBundles()) {
+            const p = this.saveArtifactBundle(bundle, pattern)
             // Run sequentially when debugging enabled
             if (this.cacheDebuggingEnabled) {
                 await p
@@ -128,28 +111,31 @@ export class GradleUserHomeCache extends AbstractCache {
         await Promise.all(processes)
     }
 
-    private async saveCommonArtifactBundle(
+    private async saveArtifactBundle(
         bundle: string,
         artifactPath: string
     ): Promise<void> {
-        const cacheMetaFile = this.getCacheMetaFile(bundle)
+        const bundleMetaFile = this.getBundleMetaFile(bundle)
 
-        const globber = await glob.create(artifactPath)
-        const commonArtifactFiles = await globber.glob()
+        const globber = await glob.create(artifactPath, {
+            implicitDescendants: false,
+            followSymbolicLinks: false
+        })
+        const bundleFiles = await globber.glob()
 
         // Handle no matching files
-        if (commonArtifactFiles.length === 0) {
+        if (bundleFiles.length === 0) {
             this.debug(`No files found to cache for ${bundle}`)
-            if (fs.existsSync(cacheMetaFile)) {
-                tryDelete(cacheMetaFile)
+            if (fs.existsSync(bundleMetaFile)) {
+                tryDelete(bundleMetaFile)
             }
             return
         }
 
-        const previouslyRestoredKey = fs.existsSync(cacheMetaFile)
-            ? fs.readFileSync(cacheMetaFile, 'utf-8').trim()
+        const previouslyRestoredKey = fs.existsSync(bundleMetaFile)
+            ? fs.readFileSync(bundleMetaFile, 'utf-8').trim()
             : ''
-        const cacheKey = this.createCacheKey(bundle, commonArtifactFiles)
+        const cacheKey = this.createCacheKey(bundle, bundleFiles)
 
         if (previouslyRestoredKey === cacheKey) {
             this.debug(
@@ -158,26 +144,39 @@ export class GradleUserHomeCache extends AbstractCache {
         } else {
             core.info(`Caching ${bundle} with cache key: ${cacheKey}`)
             await this.saveCache([artifactPath], cacheKey)
-
-            this.debug(`Writing cache metafile: ${cacheMetaFile}`)
-            fs.writeFileSync(cacheMetaFile, cacheKey)
+            this.writeBundleMetaFile(bundleMetaFile, cacheKey)
         }
 
-        for (const file of commonArtifactFiles) {
+        for (const file of bundleFiles) {
             tryDelete(file)
         }
     }
 
     protected createCacheKey(bundle: string, files: string[]): string {
-        const cacheKeyPrefix = process.env['CACHE_KEY_PREFIX'] || ''
+        const cacheKeyPrefix = getCacheKeyPrefix()
         const relativeFiles = files.map(x =>
             path.relative(this.gradleUserHome, x)
         )
         const key = hashFileNames(relativeFiles)
 
+        this.debug(
+            `Generating cache key for ${bundle} from files: ${relativeFiles}`
+        )
+
         return `${cacheKeyPrefix}${bundle}-${key}`
     }
 
+    private writeBundleMetaFile(metaFile: string, cacheKey: string): void {
+        this.debug(`Writing bundle metafile: ${metaFile}`)
+
+        const dirName = path.dirname(metaFile)
+        if (!fs.existsSync(dirName)) {
+            fs.mkdirSync(dirName)
+        }
+
+        fs.writeFileSync(metaFile, cacheKey)
+    }
+
     protected determineGradleUserHome(rootDir: string): string {
         const customGradleUserHome = process.env['GRADLE_USER_HOME']
         if (customGradleUserHome) {
@@ -194,15 +193,69 @@ export class GradleUserHomeCache extends AbstractCache {
     }
 
     protected getCachePath(): string[] {
-        return CACHE_PATH.map(x => path.resolve(this.gradleUserHome, x))
+        const rawPaths: string[] = JSON.parse(
+            core.getInput(INCLUDE_PATHS_PARAMETER)
+        )
+        rawPaths.push(META_FILE_DIR)
+        const resolvedPaths = rawPaths.map(x => this.resolveCachePath(x))
+        this.debug(`Using cache paths: ${resolvedPaths}`)
+        return resolvedPaths
     }
 
-    private getCommonArtifactPaths(): Map<string, string> {
+    private resolveCachePath(rawPath: string): string {
+        if (rawPath.startsWith('!')) {
+            const resolved = this.resolveCachePath(rawPath.substring(1))
+            return `!${resolved}`
+        }
+        return path.resolve(this.gradleUserHome, rawPath)
+    }
+
+    private getArtifactBundles(): Map<string, string> {
+        const artifactBundleDefinition = core.getInput(
+            ARTIFACT_BUNDLES_PARAMETER
+        )
+        this.debug(
+            `Using artifact bundle definition: ${artifactBundleDefinition}`
+        )
+        const artifactBundles = JSON.parse(artifactBundleDefinition)
         return new Map(
-            Array.from(COMMON_ARTIFACT_CACHES, ([key, value]) => [
+            Array.from(artifactBundles, ([key, value]) => [
                 key,
                 path.resolve(this.gradleUserHome, value)
             ])
         )
     }
+
+    private async reportGradleUserHomeSize(label: string): Promise<void> {
+        if (!this.cacheDebuggingEnabled) {
+            return
+        }
+        if (!fs.existsSync(this.gradleUserHome)) {
+            return
+        }
+        const result = await exec.getExecOutput(
+            'du',
+            ['-h', '-c', '-t', '5M'],
+            {
+                cwd: this.gradleUserHome,
+                silent: true,
+                ignoreReturnCode: true
+            }
+        )
+
+        core.info(`Gradle User Home (directories >5M): ${label}`)
+
+        core.info(
+            result.stdout
+                .trimEnd()
+                .replace(/\t/g, '    ')
+                .split('\n')
+                .map(it => {
+                    return `  ${it}`
+                })
+                .join('\n')
+        )
+
+        core.info('-----------------------')
+    }
 }

src/cache-utils.ts

@@ -5,21 +5,31 @@ import * as crypto from 'crypto'
 import * as path from 'path'
 import * as fs from 'fs'
 
+const CACHE_DISABLED_PARAMETER = 'cache-disabled'
+const CACHE_READONLY_PARAMETER = 'cache-read-only'
+const JOB_CONTEXT_PARAMETER = 'workflow-job-context'
+const CACHE_DEBUG_VAR = 'GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED'
+const CACHE_PREFIX_VAR = 'GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX'
+
 export function isCacheDisabled(): boolean {
-    return core.getBooleanInput('cache-disabled')
+    return core.getBooleanInput(CACHE_DISABLED_PARAMETER)
 }
 
 export function isCacheReadOnly(): boolean {
-    return core.getBooleanInput('cache-read-only')
+    return core.getBooleanInput(CACHE_READONLY_PARAMETER)
 }
 
 export function isCacheDebuggingEnabled(): boolean {
-    return process.env['CACHE_DEBUG_ENABLED'] ? true : false
+    return process.env[CACHE_DEBUG_VAR] ? true : false
+}
+
+export function getCacheKeyPrefix(): string {
+    // Prefix can be used to force change all cache keys (defaults to cache protocol version)
+    return process.env[CACHE_PREFIX_VAR] || 'v3-'
 }
 
 function generateCacheKey(cacheName: string): CacheKey {
-    // Prefix can be used to force change all cache keys
-    const cacheKeyPrefix = process.env['CACHE_KEY_PREFIX'] || ''
+    const cacheKeyPrefix = getCacheKeyPrefix()
 
     // At the most general level, share caches for all executions on the same OS
     const runnerOs = process.env['RUNNER_OS'] || ''
@@ -43,7 +53,7 @@ function generateCacheKey(cacheName: string): CacheKey {
 
 function determineJobContext(): string {
     // By default, we hash the full `matrix` data for the run, to uniquely identify this job invocation
-    const workflowJobContext = core.getInput('workflow-job-context')
+    const workflowJobContext = core.getInput(JOB_CONTEXT_PARAMETER)
     return hashStrings([workflowJobContext])
 }
 
@@ -62,12 +72,17 @@ export function hashFileNames(fileNames: string[]): string {
 }
 
 /**
- * Attempt to delete a file, waiting to allow locks to be released
+ * Attempt to delete a file or directory, waiting to allow locks to be released
  */
 export async function tryDelete(file: string): Promise<void> {
+    const stat = fs.lstatSync(file)
     for (let count = 0; count < 3; count++) {
         try {
+            if (stat.isDirectory()) {
+                fs.rmdirSync(file, {recursive: true})
+            } else {
                 fs.unlinkSync(file)
+            }
             return
         } catch (error) {
             if (count === 2) {
@@ -122,6 +137,12 @@ export abstract class AbstractCache {
 
         core.saveState(this.cacheKeyStateKey, cacheKey.key)
 
+        this.debug(
+            `Requesting ${this.cacheDescription} with
+                key:${cacheKey.key}
+                restoreKeys:[${cacheKey.restoreKeys}]`
+        )
+
         const cacheResult = await this.restoreCache(
             this.getCachePath(),
             cacheKey.key,
@@ -141,7 +162,13 @@ export abstract class AbstractCache {
             `Restored ${this.cacheDescription} from cache key: ${cacheResult}`
         )
 
+        try {
             await this.afterRestore()
+        } catch (error) {
+            core.warning(
+                `Restore ${this.cacheDescription} failed in 'afterRestore': ${error}`
+            )
+        }
 
         return
     }
@@ -193,7 +220,14 @@ export abstract class AbstractCache {
             return
         }
 
+        try {
             await this.beforeSave()
+        } catch (error) {
+            core.warning(
+                `Save ${this.cacheDescription} failed in 'beforeSave': ${error}`
+            )
+            return
+        }
 
         core.info(
             `Caching ${this.cacheDescription} with cache key: ${cacheKey}`

src/caches.ts

@@ -7,7 +7,9 @@ const BUILD_ROOT_DIR = 'BUILD_ROOT_DIR'
 
 export async function restore(buildRootDirectory: string): Promise<void> {
     if (isCacheDisabled()) {
-        core.debug('Cache read disabled')
+        core.info(
+            'Cache is disabled: will not restore state from previous builds.'
+        )
         return
     }
 
@@ -22,7 +24,9 @@ export async function restore(buildRootDirectory: string): Promise<void> {
 
 export async function save(): Promise<void> {
     if (isCacheReadOnly()) {
-        core.debug('Cache is read-only: not saving cache entry')
+        core.info(
+            'Cache is read-only: will not save state for use in subsequent builds.'
+        )
         return
     }
 

src/main.ts

@@ -28,13 +28,20 @@ export async function run(): Promise<void> {
 
         if (result.buildScanUrl) {
             core.setOutput('build-scan-url', result.buildScanUrl)
-            // TODO Include context about the invocation (eg step name) in this message
-            // Unfortunately it doesn't seem possible to access the current step name here
-            core.notice(`Gradle build scan: ${result.buildScanUrl}`)
         }
 
         if (result.status !== 0) {
-            core.setFailed(`Gradle process exited with status ${result.status}`)
+            if (result.buildScanUrl) {
+                core.setFailed(`Gradle build failed: ${result.buildScanUrl}`)
+            } else {
+                core.setFailed(
+                    `Gradle build failed: process exited with status ${result.status}`
+                )
+            }
+        } else {
+            if (result.buildScanUrl) {
+                core.notice(`Gradle build succeeded: ${result.buildScanUrl}`)
+            }
         }
     } catch (error) {
         core.setFailed(String(error))