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
This commit is contained in:
Daz DeBoer 2021-10-27 16:05:07 -06:00
parent cba1833dde
commit 27f2dc276c
No known key found for this signature in database
GPG key ID: DD6B9F0B06683D5D
4 changed files with 64 additions and 32 deletions

View file

@ -159,12 +159,9 @@ Caching is enabled by default. You can disable caching for the action as follows
cache-disabled: true 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 ### 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. 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. As such, the cache key is likely to change on each subsequent run of GitHub actions.
@ -183,16 +180,36 @@ 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: You can enable read-only caching for any of the caches as follows:
```yaml ```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 ### Cache debugging
It is possible to enable additional debug logging for cache operations. You do via the `CACHE_DEBUG_ENABLED` environment variable: It is possible to enable additional debug logging for cache operations. You do via the `GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED` environment variable:
```yaml ```yaml
env: env:
CACHE_DEBUG_ENABLED: true 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. Note that this setting will also prevent certain cache operations from running in parallel, further assisting with debugging.

View file

@ -26,11 +26,26 @@ inputs:
default: false default: false
cache-read-only: cache-read-only:
description: When 'true', existing entries will be read from the cache but no entries will be written description: When 'true', existing entries will be read from the cache but no entries will be written.
required: false required: false
# TODO: It might be useful to default to read-only for PRs, or non-main branch.
default: 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 # EXPERIMENTAL & INTERNAL CONFIGURATION PROPERTIES
# The following action properties allow fine-grained tweaking of the action caching behaviour. # The following action properties allow fine-grained tweaking of the action caching behaviour.
@ -40,21 +55,7 @@ inputs:
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). 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 required: false
default: ${{ toJSON(matrix) }} default: ${{ toJSON(matrix) }}
gradle-home-cache-artifact-bundles:
cache-paths:
description: Paths in Gradle User Home to cache. (EXPERIMENTAL - may be changed/removed without notice)
required: false
default: |
["caches", "notifications"]
cache-exclude-paths:
description: Paths in Gradle User Home to exclude from cache. (EXPERIMENTAL - may be changed/removed without notice)
required: false
# eg ["caches/build-cache-1"] will prevent the local build cache from being saved/restored.
default: |
[]
cache-artifact-bundles:
description: Names and patterns of artifact bundles to cache separately. (EXPERIMENTAL - may be changed/removed without notice) description: Names and patterns of artifact bundles to cache separately. (EXPERIMENTAL - may be changed/removed without notice)
required: false required: false
default: | default: |

View file

@ -14,6 +14,10 @@ import {
const META_FILE_DIR = '.gradle-build-action' const META_FILE_DIR = '.gradle-build-action'
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 { export class GradleUserHomeCache extends AbstractCache {
private gradleUserHome: string private gradleUserHome: string
@ -81,7 +85,7 @@ export class GradleUserHomeCache extends AbstractCache {
private removeExcludedPaths(): void { private removeExcludedPaths(): void {
const rawPaths: string[] = JSON.parse( const rawPaths: string[] = JSON.parse(
core.getInput('cache-exclude-paths') core.getInput(EXCLUDE_PATHS_PARAMETER)
) )
const resolvedPaths = rawPaths.map(x => const resolvedPaths = rawPaths.map(x =>
path.resolve(this.gradleUserHome, x) path.resolve(this.gradleUserHome, x)
@ -189,7 +193,9 @@ export class GradleUserHomeCache extends AbstractCache {
} }
protected getCachePath(): string[] { protected getCachePath(): string[] {
const rawPaths: string[] = JSON.parse(core.getInput('cache-paths')) const rawPaths: string[] = JSON.parse(
core.getInput(INCLUDE_PATHS_PARAMETER)
)
rawPaths.push(META_FILE_DIR) rawPaths.push(META_FILE_DIR)
const resolvedPaths = rawPaths.map(x => this.resolveCachePath(x)) const resolvedPaths = rawPaths.map(x => this.resolveCachePath(x))
this.debug(`Using cache paths: ${resolvedPaths}`) this.debug(`Using cache paths: ${resolvedPaths}`)
@ -205,7 +211,9 @@ export class GradleUserHomeCache extends AbstractCache {
} }
private getArtifactBundles(): Map<string, string> { private getArtifactBundles(): Map<string, string> {
const artifactBundleDefinition = core.getInput('cache-artifact-bundles') const artifactBundleDefinition = core.getInput(
ARTIFACT_BUNDLES_PARAMETER
)
this.debug( this.debug(
`Using artifact bundle definition: ${artifactBundleDefinition}` `Using artifact bundle definition: ${artifactBundleDefinition}`
) )

View file

@ -5,21 +5,27 @@ import * as crypto from 'crypto'
import * as path from 'path' import * as path from 'path'
import * as fs from 'fs' 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 { export function isCacheDisabled(): boolean {
return core.getBooleanInput('cache-disabled') return core.getBooleanInput(CACHE_DISABLED_PARAMETER)
} }
export function isCacheReadOnly(): boolean { export function isCacheReadOnly(): boolean {
return core.getBooleanInput('cache-read-only') return core.getBooleanInput(CACHE_READONLY_PARAMETER)
} }
export function isCacheDebuggingEnabled(): boolean { export function isCacheDebuggingEnabled(): boolean {
return process.env['CACHE_DEBUG_ENABLED'] ? true : false return process.env[CACHE_DEBUG_VAR] ? true : false
} }
export function getCacheKeyPrefix(): string { export function getCacheKeyPrefix(): string {
// Prefix can be used to force change all cache keys (defaults to cache protocol version) // Prefix can be used to force change all cache keys (defaults to cache protocol version)
return process.env['CACHE_KEY_PREFIX'] || 'v3-' return process.env[CACHE_PREFIX_VAR] || 'v3-'
} }
function generateCacheKey(cacheName: string): CacheKey { function generateCacheKey(cacheName: string): CacheKey {
@ -47,7 +53,7 @@ function generateCacheKey(cacheName: string): CacheKey {
function determineJobContext(): string { function determineJobContext(): string {
// By default, we hash the full `matrix` data for the run, to uniquely identify this job invocation // 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]) return hashStrings([workflowJobContext])
} }