Publishing Catalogs

Author, validate, and host a datumctl plugin catalog so users and enterprises can discover and install your plugins.

A catalog is a single manifest file — an index.yaml — that lists the plugins you publish, their versions, and per-platform download URLs and checksums. Users register your catalog with datumctl plugin index add, then search, browse, and install from it like any other.

This guide covers the manifest format, validation, hosting, and versioning guidance.

If you’re writing the plugin itself (not just publishing a catalog), start with Building plugins. This guide assumes you already have released plugin binaries to point at.

The catalog manifest

A catalog manifest is a PluginList document. It has an optional catalog-level identity header followed by an items list of plugin entries. Here is a complete, annotated example:

apiVersion: datumctl.datum.net/v1alpha1
kind: PluginList

# Optional catalog identity, shown in `plugin index list` and `plugin browse`.
name: acme
description: ACME internal datumctl plugins
owner: ACME Platform Team
homepage: https://plugins.acme.example

items:
  - apiVersion: datumctl.datum.net/v1alpha1
    kind: Plugin
    metadata:
      name: deploy                       # the name users install and run
    spec:
      shortDescription: Deploy ACME workloads to Datum Cloud
      description: |
        Longer description shown when inspecting the plugin in the browser.
      homepage: https://github.com/acme-corp/datumctl-deploy
      version: v1.2.0                     # the recommended version to install
      platforms:
        - selector:
            matchLabels:
              os: linux
              arch: amd64
          uri: https://github.com/acme-corp/datumctl-deploy/releases/download/v1.2.0/datumctl-deploy_Linux_x86_64.tar.gz
          sha256: <lowercase hex sha256 of the archive>
        - selector:
            matchLabels:
              os: darwin
              arch: arm64
          uri: https://github.com/acme-corp/datumctl-deploy/releases/download/v1.2.0/datumctl-deploy_Darwin_arm64.tar.gz
          sha256: <lowercase hex sha256 of the archive>

Field reference

Catalog header (all optional):

Field	Purpose
name	Friendly catalog name shown in listings.
description	One-line description of the catalog.
owner	Who maintains the catalog.
homepage	Catalog homepage URL.

A manifest with no header still parses — the only required content is the plugin list.

Each entry under items (spec):

Field	Required	Purpose
metadata.name	Yes	The name users install and run (lowercase letters, digits, hyphens).
spec.version	Yes	The recommended version to install.
spec.shortDescription	Recommended	Shown in search and browse.
spec.description	Optional	Longer text shown when inspecting the plugin.
spec.homepage	Optional	The plugin’s homepage.
spec.platforms	Yes	One entry per supported OS/arch.

Each entry under spec.platforms:

Field	Required	Purpose
selector.matchLabels	Yes	Matched against {os: <GOOS>, arch: <GOARCH>} to pick the right archive.
uri	Yes	HTTPS URL of the release archive (.tar.gz, .tgz, or .zip).
sha256	Yes	Lowercase hex SHA256 of the archive, verified on download.
files	Optional	from/to directives naming the binary to extract from the archive.

Every uri must be HTTPS. datumctl rejects an entire catalog manifest if any download URI uses a non-HTTPS scheme.

The binary inside each archive should be named datumctl-<name> (or datumctl-<name>.exe on Windows). datumctl runs it as datumctl <name>.

Validating before you publish

Lint a manifest before you ship it. The validator reports missing plugin names or versions, missing or non-HTTPS download URIs, missing checksums, and invalid platform selectors:

# Validate a local manifest
datumctl plugin index validate ./index.yaml

# Validate a published manifest
datumctl plugin index validate https://plugins.acme.example/index.yaml

The source may be a local path, an HTTPS URL, or a GitHub owner/repo. A clean manifest reports OK: manifest is valid.

Hosting your catalog

datumctl fetches catalog manifests over HTTPS only. You can host index.yaml in either of these ways:

• A GitHub repository. Place index.yaml at the repository root. Users then add it with the owner/repo shorthand:

  datumctl plugin index add acme acme-corp/datumctl-plugins
  

  datumctl fetches from the default branch (main, falling back to master).

• Any HTTPS host. Serve index.yaml from your own site and have users add the full URL:

  datumctl plugin index add acme https://plugins.acme.example/index.yaml
  

Publisher scoping for enterprises

Enterprises can constrain which catalogs their users may add through an allow-list, and GitHub sources are scoped by owner (and optionally repository). To make your catalog easy for enterprises to approve:

• Host it under a stable GitHub owner or repository so it can be allow-listed as github.com/<owner> or github.com/<owner>/<repo>, or under a stable dedicated hostname for a host-pattern allow-list entry.
• Avoid moving the catalog between owners or hosts, which would require every enterprise to update their allow-list.

See Adding catalogs for how allow-list entries are matched.

Versioning guidance

spec.version is the version datumctl installs when a user runs datumctl plugin install <name> without pinning. Users can pin a specific version with datumctl plugin install <name>@<version>.

To make pinning reliable for your users:

• Use consistent, sortable version strings (semantic versioning, e.g. v1.2.0) so newer releases are recognized as updates.
• Keep spec.version, the archive uri, and its sha256 in lockstep — bump all three together for each release.
• Publish immutable release archives at stable URLs so a pinned version keeps resolving to the same bytes.

Next steps

• Building plugins — write the plugin binaries your catalog points at
• Adding catalogs — how users register and trust your catalog