feat: reuse the goreleaser binary from the runner tool cache (#577)

* feat: cache the goreleaser binary

Look for GoReleaser in the runner tool cache before a download. This
makes a second use of the action in the same job, or any job on a
self-hosted runner, install immediately.

Add an opt-in `cache-binary` input that also stores the binary in the
GitHub Actions cache. When it hits, the action does not download the
release archive, the checksums and the signature bundle again. Cache
errors are not fatal and fall back to a download.

The runner tool cache entry is now keyed by distribution, so a Pro
binary is no longer returned for an OSS install of the same version.

Closes #476

Co-authored-by: timbretimber <105982513+timbretimber@users.noreply.github.com>
Co-authored-by: Akkuman <akkumans@qq.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

* refactor: collapse the duplicated zip extract branches

Both branches called extractZip with the same destination after the
install rewrite, so only the source path differs now.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4eaf86fa-a85b-41f6-8763-612acc1ccc39
Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

* fix: drop the GitHub Actions cache layer, keep the tool cache lookup

Review found that the GitHub Actions cache layer cost more than it
saved. Measured on ubuntu-latest, same job, same version:

  cold: download + checksum + cosign + extract   0.93 s
  cache hit: restore the 24 MB entry             1.28 s
  first run also pays a save                    +2.26 s

It is slower than a download in every configuration measured, because a
GitHub-hosted runner reaches the release CDN in about 0.4 s for a 15 MB
archive, and the cached entry is the larger extracted directory.

It also skipped the sha256 and cosign verification on a hit, which is
the control it was supposed to protect, and the only case where it wins
on time is when cosign is installed, which is exactly the case where
skipping is wrong. It cost 875 KB (+120%) of dist/index.js for every
user and 24 MB of repository cache quota per version and platform.

The restore and save wrappers were also dead code: @actions/cache
catches everything except ValidationError internally, so the try/catch
and the ReserveCacheError classification could never run.

What remains is the runner tool cache lookup, which is what #476 asked
for, and the distribution-keyed tool name that stops a Pro binary being
returned for an OSS install.

The tool cache test asserted that two installs return the same path, but
that path is a pure function of the tool, version and architecture: it
passed even with the tool cache wiped between the calls. It now asserts
that the second install reports a tool cache hit and does not download,
and it was verified to fail when the lookup is removed.

Co-authored-by: timbretimber <105982513+timbretimber@users.noreply.github.com>
Co-authored-by: Akkuman <akkumans@qq.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4eaf86fa-a85b-41f6-8763-612acc1ccc39
Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

* docs: drop the GitHub Actions cache rationale from the README

Review feedback: the paragraph explaining why the action does not use the
GitHub Actions cache is not needed. The measurements stay in the pull
request for anyone who asks again.

Also rebuilds dist for js-yaml 5.4.1, merged from master in #578.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4eaf86fa-a85b-41f6-8763-612acc1ccc39
Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

* fix(cache): preserve verification guarantees

Keep checksum-skipped downloads out of the persistent tool cache and separate checksum-only entries from cosign-verified entries.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 5abc512e-338c-4459-98ea-d3606438d56a
Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

---------

Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>
Co-authored-by: timbretimber <105982513+timbretimber@users.noreply.github.com>
Co-authored-by: Akkuman <akkumans@qq.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4eaf86fa-a85b-41f6-8763-612acc1ccc39
Copilot-Session: 5abc512e-338c-4459-98ea-d3606438d56a

README.md

@@ -21,6 +21,7 @@ ___
   * [Signing](#signing)
   * [Upload artifacts](#upload-artifacts)
   * [Install Only](#install-only)
+  * [Cache the binary](#cache-the-binary)
 * [Customizing](#customizing)
   * [inputs](#inputs)
   * [outputs](#outputs)
@@ -217,6 +218,23 @@ steps:
     run: goreleaser -v
 ```
 
+### Cache the binary
+
+The action looks for GoReleaser in the [runner tool cache][toolcache] before it
+downloads. A second use of the action in the same job, or any job on a
+self-hosted runner that already has the version, installs immediately.
+
+A binary taken from the tool cache is not verified again. The cache records
+whether checksum or checksum and cosign verification completed. When cosign is
+available, the action only reuses a signature-verified entry. A binary whose
+checksum could not be verified is used for that invocation but is not cached.
+
+On a self-hosted runner the tool cache is kept between jobs, so it must be
+trusted like the runner itself. GitHub-hosted runners start with an empty tool
+cache in every job, so they always download and verify.
+
+[toolcache]: https://github.com/actions/toolkit/tree/main/packages/tool-cache
+
 ## Customizing
 
 ### inputs

__tests__/goreleaser-cache.test.ts

@@ -0,0 +1,121 @@
+import {afterEach, beforeEach, describe, expect, it, jest} from '@jest/globals';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const find = jest.fn<(tool: string, version: string) => string>();
+const downloadTool = jest.fn<(url: string) => Promise<string>>();
+const extractTar = jest.fn<(archive: string) => Promise<string>>();
+const extractZip = jest.fn<(archive: string) => Promise<string>>();
+const cacheDir = jest.fn<(source: string, tool: string, version: string) => Promise<string>>();
+const which = jest.fn<(tool: string, check: boolean) => Promise<string>>();
+const exec = jest.fn<(command: string, args: string[]) => Promise<number>>();
+
+jest.unstable_mockModule('@actions/tool-cache', () => ({
+  find,
+  downloadTool,
+  extractTar,
+  extractZip,
+  cacheDir
+}));
+jest.unstable_mockModule('@actions/io', () => ({which}));
+jest.unstable_mockModule('@actions/exec', () => ({exec}));
+
+const goreleaser = await import('../src/goreleaser');
+
+describe('runner tool cache verification', () => {
+  let tempDir: string;
+  let archivePath: string;
+  let checksumsPath: string;
+  let bundlePath: string;
+  let extractedPath: string;
+  let cosignPath: string;
+  let cache: Map<string, string>;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'goreleaser-cache-'));
+    archivePath = path.join(tempDir, 'archive');
+    checksumsPath = path.join(tempDir, 'checksums.txt');
+    bundlePath = path.join(tempDir, 'checksums.txt.sigstore.json');
+    extractedPath = path.join(tempDir, 'extracted');
+    fs.writeFileSync(archivePath, 'archive');
+    fs.writeFileSync(bundlePath, '{}');
+    fs.mkdirSync(extractedPath);
+
+    const checksum = crypto.createHash('sha256').update('archive').digest('hex');
+    fs.writeFileSync(
+      checksumsPath,
+      [
+        `${checksum}  goreleaser_Linux_x86_64.tar.gz`,
+        `${checksum}  goreleaser_Darwin_all.tar.gz`,
+        `${checksum}  goreleaser_Windows_x86_64.zip`
+      ].join('\n')
+    );
+
+    cosignPath = '';
+    cache = new Map();
+    find.mockImplementation((tool, version) => cache.get(`${tool}:${version}`) || '');
+    downloadTool.mockImplementation(async url => {
+      if (url.endsWith('/checksums.txt')) {
+        return checksumsPath;
+      }
+      if (url.endsWith('/checksums.txt.sigstore.json')) {
+        return bundlePath;
+      }
+      return archivePath;
+    });
+    extractTar.mockResolvedValue(extractedPath);
+    extractZip.mockResolvedValue(extractedPath);
+    cacheDir.mockImplementation(async (_source, tool, version) => {
+      const destination = path.join(tempDir, tool, version);
+      cache.set(`${tool}:${version}`, destination);
+      return destination;
+    });
+    which.mockImplementation(async () => cosignPath);
+    exec.mockResolvedValue(0);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, {recursive: true, force: true});
+  });
+
+  it('does not cache a binary when checksum verification is skipped', async () => {
+    downloadTool.mockImplementation(async url => {
+      if (url.endsWith('/checksums.txt')) {
+        throw new Error('checksums unavailable');
+      }
+      return archivePath;
+    });
+
+    await goreleaser.install('goreleaser', 'v2.15.3');
+    await goreleaser.install('goreleaser', 'v2.15.3');
+
+    expect(cacheDir).not.toHaveBeenCalled();
+    expect(downloadTool.mock.calls.filter(([url]) => !url.endsWith('/checksums.txt'))).toHaveLength(2);
+  });
+
+  it('does not reuse a checksum-only entry when cosign becomes available', async () => {
+    await goreleaser.install('goreleaser', 'v2.15.3');
+    expect(cacheDir).toHaveBeenLastCalledWith(extractedPath, 'goreleaser-checksum', '2.15.3');
+
+    cosignPath = '/usr/local/bin/cosign';
+    await goreleaser.install('goreleaser', 'v2.15.3');
+    await goreleaser.install('goreleaser', 'v2.15.3');
+
+    expect(exec).toHaveBeenCalledTimes(1);
+    expect(cacheDir).toHaveBeenLastCalledWith(extractedPath, 'goreleaser-cosign', '2.15.3');
+    expect(downloadTool.mock.calls.filter(([url]) => !url.includes('checksums.txt'))).toHaveLength(2);
+  });
+
+  it('reuses checksum verification for releases without sigstore bundles', async () => {
+    cosignPath = '/usr/local/bin/cosign';
+
+    await goreleaser.install('goreleaser', 'v2.12.4');
+    await goreleaser.install('goreleaser', 'v2.12.4');
+
+    expect(exec).not.toHaveBeenCalled();
+    expect(cacheDir).toHaveBeenCalledTimes(1);
+    expect(downloadTool.mock.calls.filter(([url]) => !url.includes('checksums.txt'))).toHaveLength(1);
+  });
+});

__tests__/goreleaser.test.ts

@@ -57,6 +57,38 @@ describe('install', () => {
     const bin = await goreleaser.install('goreleaser-pro', 'latest');
     expect(fs.existsSync(bin)).toBe(true);
   }, 100000);
+
+  it('reuses the runner tool cache instead of downloading again', async () => {
+    const first = await goreleaser.install('goreleaser', 'v2.15.3');
+
+    const written: string[] = [];
+    const stdout = process.stdout.write.bind(process.stdout);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = ((chunk: any, ...rest: any[]): boolean => {
+      written.push(chunk.toString());
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return (stdout as any)(chunk, ...rest);
+    }) as typeof process.stdout.write;
+    let second: string;
+    try {
+      second = await goreleaser.install('goreleaser', 'v2.15.3');
+    } finally {
+      process.stdout.write = stdout;
+    }
+
+    const logs = written.join('');
+    expect(logs).toContain('found in the runner tool cache');
+    expect(logs).not.toContain('Downloading https://github.com/goreleaser');
+    expect(second).toEqual(first);
+    expect(fs.existsSync(second)).toBe(true);
+  }, 100000);
+
+  it('does not share the tool cache between distributions', async () => {
+    const oss = await goreleaser.install('goreleaser', 'v2.15.3');
+    const pro = await goreleaser.install('goreleaser-pro', 'v2.15.3');
+    expect(pro).not.toEqual(oss);
+    expect(fs.existsSync(pro)).toBe(true);
+  }, 100000);
 });
 
 describe('distribSuffix', () => {

src/goreleaser.ts

@@ -8,49 +8,83 @@ import * as core from '@actions/core';
 import * as exec from '@actions/exec';
 import * as io from '@actions/io';
 import * as tc from '@actions/tool-cache';
+import * as semver from 'semver';
+
+type VerificationLevel = 'checksum' | 'cosign';
 
 export async function install(distribution: string, version: string): Promise<string> {
   const release: github.GitHubRelease = await github.getRelease(distribution, version);
+  const tag = release.tag_name;
+  const toolVersion = tag.replace(/^v/, '');
+  const cosign = await io.which('cosign', false);
+  const verificationLevel = cosign && supportsCosignBundle(tag) ? 'cosign' : 'checksum';
+
+  const toolPath = findCachedTool(distribution, toolVersion, verificationLevel);
+  if (toolPath) {
+    core.info(`GoReleaser ${tag} found in the runner tool cache: ${toolPath}`);
+    return getExePath(toolPath);
+  }
+
   const filename = getFilename(distribution);
-  const baseUrl = `https://github.com/goreleaser/${distribution}/releases/download/${release.tag_name}`;
+  const baseUrl = `https://github.com/goreleaser/${distribution}/releases/download/${tag}`;
   const downloadUrl = `${baseUrl}/${filename}`;
 
   core.info(`Downloading ${downloadUrl}`);
   const downloadPath: string = await tc.downloadTool(downloadUrl);
   core.debug(`Downloaded to ${downloadPath}`);
 
-  await verifyChecksum(distribution, release.tag_name, downloadPath, filename);
+  const verified = await verifyChecksum(distribution, tag, downloadPath, filename, cosign);
 
   core.info('Extracting GoReleaser');
   let extPath: string;
   if (context.osPlat == 'win32') {
-    if (!downloadPath.endsWith('.zip')) {
-      const newPath = downloadPath + '.zip';
-      fs.renameSync(downloadPath, newPath);
-      extPath = await tc.extractZip(newPath);
-    } else {
-      extPath = await tc.extractZip(downloadPath);
+    let zipPath = downloadPath;
+    if (!zipPath.endsWith('.zip')) {
+      zipPath = `${downloadPath}.zip`;
+      fs.renameSync(downloadPath, zipPath);
     }
+    extPath = await tc.extractZip(zipPath);
   } else {
     extPath = await tc.extractTar(downloadPath);
   }
   core.debug(`Extracted to ${extPath}`);
 
-  const cachePath: string = await tc.cacheDir(extPath, 'goreleaser-action', release.tag_name.replace(/^v/, ''));
+  if (!verified) {
+    return getExePath(extPath);
+  }
+
+  const cachePath: string = await tc.cacheDir(extPath, cacheToolName(distribution, verified), toolVersion);
   core.debug(`Cached to ${cachePath}`);
 
-  const exePath: string = path.join(cachePath, context.osPlat == 'win32' ? 'goreleaser.exe' : 'goreleaser');
-  core.debug(`Exe path is ${exePath}`);
-
-  return exePath;
+  return getExePath(cachePath);
 }
 
+const findCachedTool = (distribution: string, version: string, required: VerificationLevel): string => {
+  const levels: VerificationLevel[] = required === 'cosign' ? ['cosign'] : ['cosign', 'checksum'];
+  for (const level of levels) {
+    const toolPath = tc.find(cacheToolName(distribution, level), version);
+    if (toolPath) {
+      return toolPath;
+    }
+  }
+  return '';
+};
+
+const cacheToolName = (distribution: string, verification: VerificationLevel): string => {
+  return `${distribution}-${verification}`;
+};
+
+const getExePath = (dir: string): string => {
+  return path.join(dir, context.osPlat == 'win32' ? 'goreleaser.exe' : 'goreleaser');
+};
+
 export async function verifyChecksum(
   distribution: string,
   tag: string,
   archivePath: string,
-  filename: string
-): Promise<void> {
+  filename: string,
+  cosign?: string
+): Promise<VerificationLevel | undefined> {
   const baseUrl = `https://github.com/goreleaser/${distribution}/releases/download/${tag}`;
   let checksumsPath: string;
   try {
@@ -71,7 +105,19 @@ export async function verifyChecksum(
   }
   core.info(`Checksum verified for ${filename}`);
 
-  await verifyCosignSignature(distribution, tag, baseUrl, checksumsPath);
+  const cosignPath = cosign === undefined ? await io.which('cosign', false) : cosign;
+  if (!cosignPath) {
+    core.info('cosign not found in PATH, skipping signature verification');
+    return 'checksum';
+  }
+  if (!supportsCosignBundle(tag)) {
+    core.info(`GoReleaser ${tag} does not have a sigstore bundle, skipping signature verification`);
+    return 'checksum';
+  }
+  if (!(await verifyCosignSignature(distribution, tag, baseUrl, checksumsPath, cosignPath))) {
+    return 'checksum';
+  }
+  return 'cosign';
 }
 
 export const findChecksum = (checksumsContent: string, filename: string): string | undefined => {
@@ -86,21 +132,16 @@ async function verifyCosignSignature(
   distribution: string,
   tag: string,
   baseUrl: string,
-  checksumsPath: string
-): Promise<void> {
-  const cosign = await io.which('cosign', false);
-  if (!cosign) {
-    core.info('cosign not found in PATH, skipping signature verification');
-    return;
-  }
-
+  checksumsPath: string,
+  cosign: string
+): Promise<boolean> {
   let bundlePath: string;
   try {
     core.info(`Downloading ${baseUrl}/checksums.txt.sigstore.json`);
     bundlePath = await tc.downloadTool(`${baseUrl}/checksums.txt.sigstore.json`);
   } catch (e) {
     core.warning(`Skipping cosign signature verification: unable to download sigstore bundle: ${e.message}`);
-    return;
+    return false;
   }
 
   const certificateIdentity = getCertificateIdentity(distribution, tag);
@@ -116,8 +157,17 @@ async function verifyCosignSignature(
     checksumsPath
   ]);
   core.info('cosign signature verified');
+  return true;
 }
 
+const supportsCosignBundle = (tag: string): boolean => {
+  if (github.isNightlyTag(tag)) {
+    return true;
+  }
+  const version = semver.parse(tag.replace(/^v/, '').replace(/-pro$/, ''));
+  return version !== null && semver.gte(version, '2.13.0');
+};
+
 export const getCertificateIdentity = (distribution: string, tag: string): string => {
   const pro = isPro(distribution);
   if (github.isNightlyTag(tag)) {