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
This commit is contained in:
Daz DeBoer 2021-10-28 00:18:36 +02:00 committed by GitHub
commit db2b34260f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 84 additions and 52 deletions

View File

@ -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:

View File

@ -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:
action-inputs:

View File

@ -6,8 +6,8 @@ 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:
# Run initial Gradle builds to push initial cache entries
@ -27,11 +27,11 @@ jobs:
arguments: test
# Add "wrapper" to main cache entry and remove 'wrapper-zips' bundle
# Exclude build-cache from main cache entry
cache-paths: |
gradle-home-cache-includes: |
["caches", "notifications", "wrapper"]
cache-exclude-paths: |
gradle-home-cache-excludes: |
["caches/build-cache-1"]
cache-artifact-bundles: |
gradle-home-cache-artifact-bundles: |
[
["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
["dependency-jars", "caches/modules-*/files-*/**/*.jar"],
@ -56,11 +56,11 @@ jobs:
arguments: test --offline
cache-read-only: true
# Need the same configuration when restoring state from cache
cache-paths: |
gradle-home-cache-includes: |
["caches", "notifications", "wrapper"]
cache-exclude-paths: |
gradle-home-cache-excludes: |
["caches/build-cache-1"]
cache-artifact-bundles: |
gradle-home-cache-artifact-bundles: |
[
["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
["dependency-jars", "caches/modules-*/files-*/**/*.jar"],

View File

@ -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
@ -98,6 +98,6 @@ jobs:
with:
build-root-directory: __tests__/samples/groovy-dsl
arguments: test
cache-artifact-bundles: '[]'
cache-read-only: true
gradle-home-cache-artifact-bundles: '[]'

View File

@ -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.

View File

@ -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}}-
GRADLE_USER_HOME: custom/gradle/home
jobs:

View File

@ -6,8 +6,8 @@ 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

View File

@ -159,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.
@ -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:
```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 `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
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.

View File

@ -26,11 +26,26 @@ inputs:
default: false
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
# TODO: It might be useful to default to read-only for PRs, or non-main branch.
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.
@ -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).
required: false
default: ${{ toJSON(matrix) }}
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:
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: |

2
dist/main/index.js vendored

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

2
dist/post/index.js vendored

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View File

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

View File

@ -5,21 +5,27 @@ 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_KEY_PREFIX'] || 'v3-'
return process.env[CACHE_PREFIX_VAR] || 'v3-'
}
function generateCacheKey(cacheName: string): CacheKey {
@ -47,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])
}