feat: add improve headlamp publish action

Signed-off-by: Oliver Baehler <oliver@sudo-i.net>

Author: oliverbaehler

README.md

@@ -8,7 +8,7 @@ reviewed commit SHA in production.
 | Action | Purpose |
 | --- | --- |
 | [headlamp-test](headlamp-test/README.md) | Lint, check formatting and types, test, and build a Headlamp plugin from a configurable directory. Includes a workflow template. |
-| [headlamp-publish](headlamp-publish/README.md) | Build a Headlamp plugin, upload its GitHub release archive, and publish versioned Artifact Hub metadata to a configurable branch. |
+| [headlamp-publish](headlamp-publish/README.md) | Build a Headlamp plugin or reuse an already published archive, then publish versioned Artifact Hub metadata to a configurable branch. |
 | [helm-oci-chart](helm-oci-chart/README.md) | Package and push a Helm chart to an OCI registry, with optional signing. |
 | [task-ko-publish](task-ko-publish/README.md) | Publish a ko image through a Task target, generate and attach a CycloneDX SBOM, and optionally sign it. |
 | [exists](exists/README.md) | Return whether an input is nonempty. |

headlamp-publish/README.md

@@ -6,6 +6,11 @@ Builds a plugin with `npm ci`, `npm run build`, and `npm run package`; uploads i
 to `headlamp/`. Container-image building, signing, and attestations can follow as
 separate steps in the caller's workflow.
 
+When GoReleaser or another release tool already packages, signs, and uploads the
+plugin, pass its archive through `archive` to publish only the Artifact Hub
+metadata. The action verifies the released archive's checksum without rebuilding
+the plugin, changing source package files, or creating or uploading release assets.
+
 ```yaml
 name: Publish Headlamp plugin
 on:
@@ -45,19 +50,50 @@ in the source checkout, without committing them.
 | Input | Default | Meaning |
 | --- | --- | --- |
 | `build-root` | `headlamp/` | Plugin path relative to `GITHUB_WORKSPACE`; `.` builds at the repository root. |
+| `archive` | empty | Prebuilt `.tar.gz` path or glob relative to `GITHUB_WORKSPACE`; must match exactly one file already attached to the published release. Skips plugin installation, version changes, building, packaging, and release uploads. |
 | `target-branch` | `artifacthub` | Branch to update or create for metadata. |
 | `tag` | `github.ref_name` | Existing tag matching the checked-out commit; exact SemVer with optional `v`, including prereleases, without `+` build metadata. |
 | `package-name` | `package.json` name | Artifact Hub package name and directory; lowercase letters, digits, and hyphens. Override this for scoped npm names. |
 | `metadata-template` | automatic | Optional YAML template path relative to `build-root`. |
 | `node-version` | `24` | Node.js version, at least 24. |
 | `token` | `github.token` | Token with `contents: write` in the caller repository. |
 
-Requires an Ubuntu runner, a checked-out repository, `package.json`, a compatible
-`package-lock.json`, and working `build` and `package` npm scripts. Packaging must
+Requires an Ubuntu runner, a checked-out repository, and `package.json`.
+Without `archive`, also requires a compatible
+`package-lock.json` and working `build` and `package` npm scripts. Packaging must
 produce exactly one nonempty `.tar.gz` directly in `build-root`, which must not
 already contain archives. Run the plugin's own lint and test checks before this
 action. The action executes the plugin's trusted npm scripts.
 
+## Combining with GoReleaser
+
+Include the plugin archive in GoReleaser's archives, checksums, SBOMs, and Cosign
+signing. Publish all assets together before the release becomes immutable, then
+invoke this action with the exact archive that GoReleaser uploaded:
+
+```yaml
+- name: Publish release artifacts
+  run: devbox run -- task release
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+- uses: projectcapsule/github-actions/headlamp-publish@main
+  with:
+    build-root: headlamp/
+    archive: dist/resource-permits-*.tar.gz
+    target-branch: headlamp-plugin
+    metadata-template: artifacthub-pkg.yml
+```
+
+Pin a reviewed action commit SHA in production. Run this only after the release
+tool succeeds, in the same tag-only job with `contents: write`. Keep pull-request
+checks in a separate read-only workflow.
+
+The glob must identify one nonempty archive within the source checkout. Symlinks
+and paths escaping the checkout are rejected. Existing releases and assets must
+already exist and match the local SHA-256. A missing release, missing asset, or
+checksum mismatch fails before publishing metadata. Cosign bundles remain owned
+by the release tool; this action leaves all release assets intact.
+
 ## Metadata and first publication
 
 Templates are selected in this order:

headlamp-publish/action.yaml

@@ -1,5 +1,5 @@
 name: Publish Headlamp plugin
-description: Build a plugin, publish its GitHub release archive, and update an Artifact Hub branch.
+description: Build or reuse a plugin archive and publish versioned Artifact Hub metadata.
 
 inputs:
   token:
@@ -10,6 +10,9 @@ inputs:
     description: Plugin directory relative to the checked-out repository.
     required: false
     default: headlamp/
+  archive:
+    description: Prebuilt .tar.gz path or glob relative to the checkout. Must match one archive already attached to the release; skips plugin builds and release uploads.
+    required: false
   target-branch:
     description: Branch containing the versioned Artifact Hub metadata.
     required: false
@@ -61,12 +64,13 @@ runs:
       env:
         ACTION_PATH: ${{ github.action_path }}
       run: npm ci --ignore-scripts --no-audit --no-fund --prefix "$ACTION_PATH/.."
-    - name: Build and package plugin
+    - name: Prepare plugin archive
       id: build
       shell: bash
       env:
         ACTION_PATH: ${{ github.action_path }}
         INPUT_BUILD_ROOT: ${{ inputs.build-root }}
+        INPUT_ARCHIVE: ${{ inputs.archive }}
         INPUT_TARGET_BRANCH: ${{ inputs.target-branch }}
         INPUT_TAG: ${{ inputs.tag }}
         INPUT_PACKAGE_NAME: ${{ inputs.package-name }}
@@ -79,7 +83,7 @@ runs:
         STATE_FILE: ${{ steps.build.outputs.state }}
         GH_TOKEN: ${{ inputs.token }}
       run: node "$ACTION_PATH/publish.mjs" prepare
-    - name: Publish release archive
+    - name: Verify or publish release archive
       shell: bash
       env:
         ACTION_PATH: ${{ github.action_path }}

headlamp-publish/publish.mjs

@@ -87,28 +87,38 @@ export function build(env = process.env) {
   }
   const template = env.INPUT_METADATA_TEMPLATE ? within(root, env.INPUT_METADATA_TEMPLATE) : null;
   if (template && !fs.statSync(template).isFile()) throw new Error('Metadata template must be a file');
-  if (fs.readdirSync(root).some(file => file.endsWith('.tar.gz'))) {
-    throw new Error('Remove existing .tar.gz archives from build-root before packaging');
-  }
   const sourceCommit = run('git', ['rev-parse', 'HEAD'], { cwd: workspace });
-  const options = { cwd: root, env, stdio: 'inherit' };
-  run('npm', ['ci', '--no-audit', '--no-fund'], options);
-  run('npm', ['version', version, '--no-git-tag-version', '--allow-same-version', '--ignore-scripts'], options);
-  run('npm', ['run', 'build'], options);
-  run('npm', ['run', 'package'], options);
-  const archives = fs.readdirSync(root).filter(file => file.endsWith('.tar.gz'));
-  if (archives.length !== 1) throw new Error('Packaging must produce exactly one .tar.gz archive in build-root');
-  const archive = within(root, archives[0]);
+  const prebuilt = Boolean(env.INPUT_ARCHIVE);
+  let archive;
+  if (prebuilt) {
+    within(workspace, env.INPUT_ARCHIVE);
+    const archives = fs.globSync(env.INPUT_ARCHIVE, { cwd: workspace });
+    if (archives.length !== 1) throw new Error('archive must match exactly one .tar.gz file within the checkout');
+    archive = within(workspace, archives[0]);
+    if (!archive.endsWith('.tar.gz')) throw new Error('archive must be a .tar.gz file');
+  } else {
+    if (fs.readdirSync(root).some(file => file.endsWith('.tar.gz'))) {
+      throw new Error('Remove existing .tar.gz archives from build-root before packaging');
+    }
+    const options = { cwd: root, env, stdio: 'inherit' };
+    run('npm', ['ci', '--no-audit', '--no-fund'], options);
+    run('npm', ['version', version, '--no-git-tag-version', '--allow-same-version', '--ignore-scripts'], options);
+    run('npm', ['run', 'build'], options);
+    run('npm', ['run', 'package'], options);
+    const archives = fs.readdirSync(root).filter(file => file.endsWith('.tar.gz'));
+    if (archives.length !== 1) throw new Error('Packaging must produce exactly one .tar.gz archive in build-root');
+    archive = within(root, archives[0]);
+  }
   if (!fs.statSync(archive).isFile() || fs.statSync(archive).size === 0) throw new Error('Plugin archive is empty or not a file');
   const server = env.GITHUB_SERVER_URL || 'https://github.com';
   const directory = fs.mkdtempSync(path.join(env.RUNNER_TEMP || os.tmpdir(), 'headlamp-publish-'));
   const state = {
     stateFile: path.join(directory, 'state.json'), directory, root, workspace,
-    sourceCommit, tag, version, branch, name, template, archive, checksum: sha256(archive),
+    sourceCommit, tag, version, branch, name, template, archive, prebuilt, checksum: sha256(archive),
     repository: env.GITHUB_REPOSITORY, server,
     api: env.GITHUB_API_URL || 'https://api.github.com',
     remote: `${server}/${env.GITHUB_REPOSITORY}.git`,
-    archiveURL: `${server}/${env.GITHUB_REPOSITORY}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(archives[0])}`,
+    archiveURL: `${server}/${env.GITHUB_REPOSITORY}/releases/download/${encodeURIComponent(tag)}/${encodeURIComponent(path.basename(archive))}`,
     metadataPath: `${name}/${version}/artifacthub-pkg.yml`,
   };
   save(state);
@@ -236,6 +246,9 @@ export async function release(state, token, fetcher = fetch) {
     throw new Error('Release tag does not resolve to the checked-out source commit');
   }
   const found = await request(`${base}/releases/tags/${encodeURIComponent(state.tag)}`, {}, true);
+  if (!found && state.prebuilt) {
+    throw new Error('Prebuilt archive requires an existing published release; publish it before running this action');
+  }
   const published = found ? await found.json() : await (await request(`${base}/releases`, {
     method: 'POST', headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ tag_name: state.tag, name: `Release ${state.tag}`, generate_release_notes: true,
@@ -259,6 +272,12 @@ export async function release(state, token, fetcher = fetch) {
     if (digest !== `sha256:${state.checksum}`) throw new Error('Release asset already exists with different content; publish a new version');
     return;
   }
+  if (state.prebuilt) {
+    throw new Error('Prebuilt archive is not attached to the release; publish it and its signatures before metadata');
+  }
+  if (published.immutable) {
+    throw new Error('Cannot add an archive to an immutable release; include it before publication and use the archive input');
+  }
   const upload = new URL(published.upload_url.replace(/\{.*$/, ''));
   upload.searchParams.set('name', filename);
   await request(upload, { method: 'POST', headers: { 'Content-Type': 'application/gzip' }, body: await fs.openAsBlob(state.archive) });

tests/headlamp.test.mjs

@@ -42,6 +42,74 @@ function commit(checkout, message = 'fixture') {
     'commit', '--quiet', '-m', message], { cwd: checkout });
 }
 
+function prebuiltFixture(t) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'headlamp-prebuilt-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const workspace = path.join(directory, 'workspace');
+  const root = path.join(workspace, 'headlamp');
+  const dist = path.join(workspace, 'dist');
+  fs.mkdirSync(root, { recursive: true });
+  fs.mkdirSync(dist);
+  const pkg = JSON.stringify({ name: 'capsule', version: '0.0.0',
+    scripts: { build: 'exit 99', package: 'exit 99' } });
+  fs.writeFileSync(path.join(root, 'package.json'), pkg);
+  const archive = path.join(dist, 'capsule-1.2.3.tar.gz');
+  fs.writeFileSync(archive, 'prebuilt archive bytes');
+  run('git', ['init', '--quiet', workspace]);
+  commit(workspace);
+  const env = { ...process.env, GITHUB_WORKSPACE: workspace, RUNNER_TEMP: directory,
+    GITHUB_OUTPUT: path.join(directory, 'outputs'), GITHUB_REPOSITORY: 'projectcapsule/example',
+    INPUT_TAG: 'v1.2.3', INPUT_BUILD_ROOT: 'headlamp/', INPUT_ARCHIVE: 'dist/*.tar.gz' };
+  return { directory, workspace, root, dist, archive, pkg, env };
+}
+
+test('prebuilt archives skip npm and reuse an immutable release without API mutations', async t => {
+  const f = prebuiltFixture(t);
+  fs.writeFileSync(path.join(f.root, 'stale.tar.gz'), 'unrelated plugin archive');
+  const state = build(f.env);
+  assert.equal(state.archive, fs.realpathSync(f.archive));
+  assert.equal(state.prebuilt, true);
+  assert.equal(state.checksum, sha256(f.archive));
+  assert.equal(fs.readFileSync(path.join(f.root, 'package.json'), 'utf8'), f.pkg);
+  assert.equal(fs.existsSync(path.join(f.root, 'package-lock.json')), false);
+  assert.equal(fs.existsSync(path.join(f.root, 'node_modules')), false);
+  assert.equal(fs.readFileSync(f.archive, 'utf8'), 'prebuilt archive bytes');
+  assert.match(fs.readFileSync(f.env.GITHUB_OUTPUT, 'utf8'), /metadata-path=capsule\/1.2.3\/artifacthub-pkg.yml/);
+  const api = fakeGitHub(state, { exists: true, immutable: true, asset: { digest: `sha256:${state.checksum}` } });
+  await release(state, 'test-token', api.fetch);
+  assert.equal(api.calls.filter(call => ['POST', 'DELETE', 'PATCH'].includes(call.method)).length, 0);
+});
+
+test('prebuilt archive paths preserve spaces and encode the release download URL', t => {
+  const f = prebuiltFixture(t);
+  const filename = 'plugin archive.tar.gz';
+  fs.renameSync(f.archive, path.join(f.dist, filename));
+  f.env.INPUT_ARCHIVE = `dist/${filename}`;
+  const state = build(f.env);
+  assert.equal(state.archive, fs.realpathSync(path.join(f.dist, filename)));
+  assert.ok(state.archiveURL.endsWith('/v1.2.3/plugin%20archive.tar.gz'));
+});
+
+for (const [name, mutate, expected] of [
+  ['no matches', f => { f.env.INPUT_ARCHIVE = 'dist/missing*.tar.gz'; }, /exactly one/],
+  ['multiple matches', f => { fs.writeFileSync(path.join(f.dist, 'other.tar.gz'), 'other'); }, /exactly one/],
+  ['empty file', f => { fs.writeFileSync(f.archive, ''); }, /empty or not a file/],
+  ['directory', f => { fs.unlinkSync(f.archive); fs.mkdirSync(f.archive); }, /empty or not a file/],
+  ['wrong extension', f => { fs.renameSync(f.archive, path.join(f.dist, 'plugin.zip')); f.env.INPUT_ARCHIVE = 'dist/*.zip'; }, /\.tar\.gz/],
+  ['absolute path', f => { f.env.INPUT_ARCHIVE = f.archive; }, /relative path/],
+  ['path traversal', f => { f.env.INPUT_ARCHIVE = '../outside/*.tar.gz'; }, /escapes/],
+  ['archive symlink', f => { const link = path.join(f.dist, 'link.tar.gz'); fs.symlinkSync(f.archive, link); f.env.INPUT_ARCHIVE = 'dist/link.tar.gz'; }, /Symlinks/],
+  ['directory symlink', f => { fs.symlinkSync(f.dist, path.join(f.workspace, 'linked')); f.env.INPUT_ARCHIVE = 'linked/*.tar.gz'; }, /Symlinks/],
+]) {
+  test(`prebuilt archive rejects ${name} before publication`, t => {
+    const f = prebuiltFixture(t);
+    mutate(f);
+    assert.throws(() => build(f.env), expected);
+    assert.equal(fs.existsSync(f.env.GITHUB_OUTPUT), false);
+    assert.equal(fs.readFileSync(path.join(f.root, 'package.json'), 'utf8'), f.pkg);
+  });
+}
+
 test('first publication creates only the selected metadata branch, repeat is unchanged', t => {
   const { state, env } = fixture(t);
   prepare(state, env);
@@ -196,7 +264,7 @@ function fakeGitHub(state, options = {}) {
       assert.equal(init.headers.Authorization, 'Bearer test-token');
       if (address.includes('/git/ref/tags/')) return json({ object: options.annotated ? { type: 'tag', sha: 'tagsha' } : { type: 'commit', sha: options.commit || state.sourceCommit } });
       if (address.includes('/git/tags/')) return json({ object: { type: 'commit', sha: state.sourceCommit } });
-      if (address.includes('/releases/tags/')) return options.exists ? json({ id: 7 }) : json({}, options.error || 404);
+      if (address.includes('/releases/tags/')) return options.exists ? json({ id: 7, immutable: Boolean(options.immutable) }) : json({}, options.error || 404);
       if (address.endsWith('/releases') && init.method === 'POST') return json({ id: 7, upload_url: 'https://uploads.github.com/repos/projectcapsule/example/releases/7/assets{?name,label}' }, 201);
       if (address.includes('?per_page=')) return json(options.asset ? [{ id: 9, name: path.basename(state.archive), ...options.asset }] : []);
       if (address.includes('/releases/assets/9')) return new Response(fs.readFileSync(state.archive));
@@ -227,6 +295,27 @@ test('identical assets are reused with digest or download verification', async t
   }
 });
 
+test('prebuilt archives reject missing releases, missing assets, and changed bytes without API mutations', async t => {
+  const { state } = fixture(t);
+  state.prebuilt = true;
+  for (const [options, expected] of [
+    [{}, /existing published release/],
+    [{ exists: true, immutable: true }, /not attached to the release/],
+    [{ exists: true, asset: { digest: `sha256:${'b'.repeat(64)}` } }, /different content/],
+  ]) {
+    const api = fakeGitHub(state, options);
+    await assert.rejects(release(state, 'test-token', api.fetch), expected);
+    assert.equal(api.calls.filter(call => ['POST', 'DELETE', 'PATCH'].includes(call.method)).length, 0);
+  }
+});
+
+test('missing archives on immutable releases fail clearly before attempting an upload', async t => {
+  const { state } = fixture(t);
+  const api = fakeGitHub(state, { exists: true, immutable: true });
+  await assert.rejects(release(state, 'test-token', api.fetch), /Cannot add an archive to an immutable release/);
+  assert.equal(api.calls.filter(call => ['POST', 'DELETE', 'PATCH'].includes(call.method)).length, 0);
+});
+
 test('release does not overwrite different assets or hide authorization failures', async t => {
   const { state } = fixture(t);
   for (const [options, error] of [