Add update-plugin-index reusable workflow

[scotwells]

Automates keeping the datumctl plugin catalog in sync with service releases.

Today, after a service publishes a release, someone hand-edits the plugin manifest in the catalog (plugins/<name>.yaml) to bump the version and paste in the new download URLs and checksums. This reusable workflow does that automatically.

What it does

Given a plugin name, a catalog repo, and a release tag, it:

• Downloads the release’s checksums.txt.
• Sets spec.version to the release tag.
• For every platform in the manifest, rewrites the download uri to the new tag and refreshes sha256 from checksums.txt.
• Opens a PR against the catalog repo. The catalog’s existing CI validates the schema, resolves every URL, and verifies every checksum; its generator regenerates index.yaml on merge.

It fails loudly if checksums.txt is missing or an expected archive is not listed in it.

Generic across plugins

The archive→checksum mapping is driven entirely off the basenames of the manifest’s existing platforms[].uri values (goreleaser archive names carry no version, so basenames are stable across releases). Nothing about a specific plugin — name, prefix, or archive layout — is hardcoded.

Interface

Inputs: index-repo (required), plugin-name (required), version (required), plugin-file (default plugins/<plugin-name>.yaml), release-repo (default: calling repo), base-branch (default main).

Secret: PLUGIN_INDEX_TOKEN (required) — a PAT or GitHub App token with contents:write + pull-requests:write on the catalog repo. A caller’s built-in GITHUB_TOKEN is scoped to its own repo and cannot open a cross-repo PR.

Notes

• Manifest edits preserve existing formatting, comments, and quoting (round-tripped via ruamel.yaml); the diff is limited to version, URLs, and checksums.
• Docs added under docs/update-plugin-index/.
• The first consumer is milo-os/ipam, which references this branch until a tagged release is cut.

Cut a new release tag after merge so consumers can pin a version.

Related work

• First consumer of this workflow: Update cli-plugins catalog on release; fix goreleaser double-run milo-os/ipam#66
• The plugin release tooling that produces the assets it reads: Make the IPAM CLI plugin installable via datumctl milo-os/ipam#65
• Example catalog and entry it maintains: Register the IPAM CLI plugin milo-os/cli-plugins#1
• datumctl plugin marketplace: Open the datumctl plugin marketplace to third-party catalogs datumctl#224 (design: Third-party plugin indexes & marketplaces for datumctl enhancements#783)