Instructions for agents onboarding a new Flux CLI plugin into this repository.
catalog.yaml— top-level catalog listing every plugin (name, description, homepage, source, license). Schema:schemas/plugincatalog-cli-v1beta1.json.plugins/<name>.yaml— per-plugin manifest with release artifacts for every supported platform. Schema:schemas/plugin-cli-v1beta1.json.schemas/— JSON Schemas consumed bymake validate.cmd/validate/— Go validator binary used by CI..github/workflows/update-plugin.yaml— reusable workflow that fetches the latest upstream release, updates the manifest, verifies checksums and opens a PR..github/workflows/update-<name>.yaml— per-plugin dispatcher that calls the reusable workflow on a schedule.
Confirm with the maintainer or verify yourself:
- The upstream project publishes GitHub releases tagged
v<semver>. - Each release attaches a
<bin>_<version>_checksums.txtfile plustar.gzarchives for darwin/linux andziparchives for windows, coveringamd64andarm64. The archive naming must match<bin>_<version>_<os>_<arch>.<ext>. - The plugin
nameis lowercase, matches^[a-z][a-z0-9-]*$, and does NOT collide with a built-in Flux command (see the reserved list in.github/workflows/validate-catalog.yaml). - The
binname (the executable inside the archive) is known. If the binary is not at the archive root, capture the relative path — it will go inextractPathon each platform entry. - The license is a valid SPDX identifier (e.g.
Apache-2.0,AGPL-3.0).
If any prerequisite is missing, stop and ask — do not improvise archive layouts or checksum formats.
-
Add the catalog entry. Append a new item to
catalog.yamlwithname,description,homepage,source,license. Thenamemust equal the filename you will create inplugins/. -
Create the plugin manifest. Add
plugins/<name>.yamlwithapiVersion: cli.fluxcd.io/v1beta1,kind: Plugin, and the metadata fields. Seedversionswith at least one release — newest first. Useplugins/operator.yamlas the reference shape. Version strings must be bare semver (novprefix). -
Populate platform artifacts. For the initial version, download the upstream
checksums.txtand fill in one platform entry per os/arch combination the upstream actually ships. Setchecksumtosha256:<64 hex>. AddextractPathonly when the binary is not at the archive root. -
Add the update workflow. Copy
.github/workflows/update-operator.yamlto.github/workflows/update-<name>.yamland change:- workflow
name plugin:input (matches the filename)repo:input (<owner>/<repo>of the upstream)bin:input (binary name used in archive filenames)
Keep the
cronschedule (0 */6 * * *) unless the maintainer requests otherwise. The reusable workflow handles checksum download, verification, manifest update and PR creation — do not duplicate that logic. - workflow
-
Validate locally. Run
make validate. This builds the validator and checks every manifest against its JSON Schema. Fix any reported error before opening a PR. -
Commit and open a PR. Include the catalog entry, the plugin manifest, and the update workflow in a single PR titled
Add <name> plugin. CI runsvalidate-catalogwhich enforces:- schema conformance
- every
plugins/*.yamlhas a catalog entry and vice versa - no name collision with built-in commands
- Keep
versionsordered newest → oldest. The update workflow prepends new versions; manual edits should preserve that order. - Do not edit historical version entries. If a checksum was wrong, fix it in a dedicated PR and explain why.
- Platform list order: darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, windows/amd64, windows/arm64. The update workflow emits this order.
- Never add a platform the upstream does not ship —
make validatepasses but installs will 404.
- Do not add plugins whose upstream does not publish a
checksums.txtalongside its release assets. The update workflow depends on it. - Do not hand-edit
bin/artifacts — they are gitignored build output. - Do not bypass
make validatewith--no-verifyor similar. If validation fails, fix the manifest. - Do not change
apiVersionorkindvalues; they are pinned by schema.
These rules come from fluxcd/flux2/CONTRIBUTING.md and apply to every Flux repository.
- Do not add
Signed-off-byorCo-authored-bytrailers with your agent name. Only a human can legally certify the DCO. - Disclose AI assistance with an
Assisted-bytrailer naming your agent and model:Thegit commit -s -m "Add X plugin" --trailer "Assisted-by: <agent-name>/<model-id>"
-sflag adds the human'sSigned-off-byfrom their git config — do not remove it. - Commit message format: Subject in imperative mood ("Add X plugin" instead of "Adding X plugin"), capitalized, no trailing period, ≤50 characters.
- Commit body: Add a succinct explanation of what the plugin does and link to the upstream project.