github-actions-gradle-cache
/github-actions-gradle-cache
Diagnose and fix stale Gradle dependency caches in GitHub Actions by deleting the setup-gradle gradle-home caches. Claude should use this skill when a Gradle build in GitHub Actions cannot resolve a SNAPSHOT dependency, or resolves an outdated SNAPSHOT, that resolves correctly locally.
- Author
- humansintheloop-dev ↗
- Repository
- humansintheloop-dev-workflow-and-tools ↗
- Licence
- Apache-2.0
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Diagnose and fix stale Gradle dependency caches in GitHub Actions by deleting the setup-gradle gradle-home caches. Claude should use this skill when a Gradle build in GitHub Actions cannot resolve a SNAPSHOT dependency, or resolves an outdated SNAPSHOT, that resolves correctly locally.
Original author description
Diagnose and fix stale Gradle dependency caches in GitHub Actions by deleting the setup-gradle gradle-home caches. Claude should use this skill when a Gradle build in GitHub Actions cannot resolve a SNAPSHOT dependency, or resolves an outdated SNAPSHOT, that resolves correctly locally.
How it works
- Symptoms
- Diagnosis
- Fix
- Why gradle-home specifically
- Common mistakes
SKILL.md preview
---
name: github-actions-gradle-cache
description: Diagnose and fix stale Gradle dependency caches in GitHub Actions by deleting the setup-gradle gradle-home caches. Claude should use this skill when a Gradle build in GitHub Actions cannot resolve a SNAPSHOT dependency, or resolves an outdated SNAPSHOT, that resolves correctly locally.
---
# Fixing Stale SNAPSHOT Dependency Caches in GitHub Actions
When a Gradle build in GitHub Actions fails to resolve a SNAPSHOT dependency that works locally, the cause is usually stale dependency resolution metadata in the `gradle/actions/setup-gradle` cache.
## Symptoms
- **Missing newly added artifact**: `Could not find <group>:<artifact>:.` (empty version after the final colon) — the cached BOM was resolved before it included this artifact.
- **Stale SNAPSHOT version**: Build uses an outdated SNAPSHOT even though a newer one has been published — the cached resolution metadata points to the old timestamp.
- **Works locally, fails in CI**: Local builds resolve correctly because there's no stale cache (or `--refresh-dependencies` was used).
## Diagnosis
### Step 1: Verify the artifact exists remotely
```bash
curl -sI "https://<repo-url>/<group-as-path>/<artifact>/<version>/maven-metadata.xml"
```
A 200 response means the artifact is published — the problem is cache, not a missing artifact.
### Step 2: Verify local resolution
```bash
./gradlew dependencyInsight --configuration <config> --dependency <artifact> -p <project>
```
If it resolves correctly locally, the remote repository is fine.
### Step 3: Check CI cache restoration
```bash
gh run view <run-id> --log-failed 2>&1 | grep -i "cache"
```
Look for `Cache hit` and `Restored cache entry` lines, especially for `gradle-home-v1`. This cache restores `~/.gradle/caches` which contains dependency resolution metadata.
## Fix
Delete all `gradle-home` caches so Gradle re-resolves dependencies from scratch.
### Step 1: List all gradle-home caches
```bash
gh cache list --limit 1000 --key gradle-home --json id --jq '.[].id'
```
Use `--key` to filter server-side rather than grepping. Use `--limit 1000` because the default limit (30) may miss older entries. Do NOT use `--limit 0` — it is invalid.
### Step 2: Delete them all
```bash
gh cache list --limit 1000 --key gradle-home --json id --jq '.[].id' | xargs -I{} gh cache delete {}
```
### Step 3: Verify none remain
```bash
gh cache list --key gradle-home --limit 1000
```
This must return no results. The `gradle/actions/setup-gradle` action uses restore-key prefix matching — if even one old `gradle-home-v1` entry survives, it will be restored and the build will fail again.
### Step 4: Re-run the failed workflow
```bash
gh run rerun <run-id> --failed
```
## Why gradle-home specifically
The `gradle/actions/setup-gradle` action maintains several cache categories:
| Cache key prefix | Contents | Contains dependency metadata? |
|---|---|---|
| `gradle-home-v1` | `~/.gradle/caches`, notifications, setup | **Yes** — SNAPSHOT resolution timestamps and BOM metadata |
| `gradle-dependencies-v1` | `~/.gradle/caches/modules-*/files-*` | Artifact JARs only |
| `gradle-wrapper-zips-v1` | Gradle distribution | No |
| `gradle-transforms-v1` | Transform outputs | No |
Deleting `gradle-dependencies` alone is insufficient because SNAPSHOT resolution metadata (which version timestamp to use, which artifacts a BOM includes) is cached in `gradle-home`, not in `gradle-dependencies`.
## Common mistakes
- **Deleting only `gradle-dependencies` caches**: The stale metadata lives in `gradle-home`, not `gradle-dependencies`.
- **Using default `--limit`**: Old cache entries accumulate across branches and commits. Always use `--limit 1000`.
- **Not verifying all entries are deleted**: Restore-key prefix matching means a single surviving entry will be restored. Always verify with a follow-up list.
- **Claiming the artifact doesn't exist remotely**: Always verify with a direct HTTP request before concluding the artifact is unpublished.
- **Speculating beyond the evidence**: The CI log shows what caches were restored and what failed to resolve. Stick to what the log says — don't infer root causes that aren't supported by the evidence.
Versions
The database has no other skills named github-actions-gradle-cache.
Database snapshot: 13.11.2026 · package version bd8bf4e2d7dd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100github-actions-cache-optimization
GitHub Actions cache analysis and optimization. Use when investigating cache bloat, finding stale caches, optimizing keys, or comparing cache usage across repos. - 100github-workflow-gradle-template
Provides a GitHub Actions CI workflow template for Gradle/Java projects. Claude should use this skill when creating or updating CI workflows to ensure current action versions and best practices are followed. - 100finops-caches
GitHub Actions cache analysis — size, prefix/branch breakdown, stale detection. Use when investigating cache bloat, stale caches, or auditing cache key strategies. - 90ci-setup
Sets up continuous integration (GitHub Actions by default): install with cache, lint, typecheck, unit and integration tests with service containers, build, Playwright on preview deploys, and dependency/secret scanning. Use when the project has code but no CI, when CI is slow or… - 100github-actions-builder
Builds reliable, fast, and secure GitHub Actions CI/CD workflows with dependency caching, build matrices, scoped secrets, concurrency control, and reusable/composite workflows. Use this skill when the user asks to "create a GitHub Actions workflow", "set up CI", "add CI/CD",… - 90actions-cache-and-artifacts
Use when caching a dependency directory in a GitHub Action, uploading or downloading a workflow artifact, installing a toolchain or an exact package-manager version into the runner's tool cache, or storing a keyed blob against the Actions cache or an S3-compatible bucket.