Add cache-provider: external to skip Gradle User Home caching (#1059)

Users relying on an external mechanism to save/restore Gradle User Home
(e.g. Develocity Artifact Cache) previously had to set cache-disabled:
true, which is confusing since caching isn't actually disabled — it's
just not managed by this action — and the Job Summary misleadingly
reported caching as "Disabled".

cache-provider: external skips Gradle User Home restore/save (same as
cache-disabled) but reports a distinct "External" status in the Job
Summary, explaining that caching is handled by another provider.

---------

Co-authored-by: Claude Sonnet 5 <[email protected]>

sources/test/jest/cache-service-loader.test.ts

@@ -45,6 +45,51 @@ describe('getCacheService selection logic', () => {
         expect(service).toBeInstanceOf(BasicCacheService)
     })
 
+    it('returns NoOpCacheService reporting "external" when cache-provider is external', async () => {
+        const {getCacheService} = await import('../../src/cache-service-loader')
+        const mockConfig = {
+            isCacheDisabled: () => false,
+            getCacheProvider: () => CacheProvider.External
+        } as unknown as CacheConfig
+
+        const service = await getCacheService(mockConfig)
+        const report = await service.save('/home/.gradle', [], {
+            disabled: false,
+            readOnly: false,
+            writeOnly: false,
+            overwriteExisting: false,
+            strictMatch: false,
+            cleanup: 'never',
+            includes: [],
+            excludes: []
+        })
+
+        expect(report.status).toBe('external')
+        expect(report.entries).toHaveLength(0)
+    })
+
+    it('reports "external" even when cache-disabled is also true', async () => {
+        const {getCacheService} = await import('../../src/cache-service-loader')
+        const mockConfig = {
+            isCacheDisabled: () => true,
+            getCacheProvider: () => CacheProvider.External
+        } as unknown as CacheConfig
+
+        const service = await getCacheService(mockConfig)
+        const report = await service.save('/home/.gradle', [], {
+            disabled: false,
+            readOnly: false,
+            writeOnly: false,
+            overwriteExisting: false,
+            strictMatch: false,
+            cleanup: 'never',
+            includes: [],
+            excludes: []
+        })
+
+        expect(report.status).toBe('external')
+    })
+
     describe('getProviderNote', () => {
         it('returns undefined when cache is disabled', async () => {
             const {getProviderNote} = await import('../../src/cache-service-loader')
@@ -56,6 +101,16 @@ describe('getCacheService selection logic', () => {
             expect(getProviderNote(mockConfig)).toBeUndefined()
         })
 
+        it('returns undefined when cache-provider is external', async () => {
+            const {getProviderNote} = await import('../../src/cache-service-loader')
+            const mockConfig = {
+                isCacheDisabled: () => false,
+                getCacheProvider: () => CacheProvider.External
+            } as unknown as CacheConfig
+
+            expect(getProviderNote(mockConfig)).toBeUndefined()
+        })
+
         it('returns basic note for the basic provider', async () => {
             const {getProviderNote} = await import('../../src/cache-service-loader')
             const mockConfig = {

sources/test/jest/caching-report.test.ts

@@ -142,4 +142,14 @@ describe('renderCachingReport', () => {
         expect(md).toContain('<h4>Gradle State Caching - Unavailable</h4>')
         expect(md).not.toContain('<details>')
     })
+
+    it('renders a compact external report with no provider note', () => {
+        const report: CacheReport = {status: 'external', entries: []}
+        const md = renderCachingReport(report, undefined)
+
+        expect(md).toContain('<h4>Gradle State Caching - External</h4>')
+        expect(md).toContain('cached externally')
+        expect(md).not.toContain('<details>')
+        expect(md).not.toContain('DISTRIBUTION.md')
+    })
 })