Skip to main content

Publishing

There are three ways to get your plugin onto hub.sigmashake.com/plugins — pick the one that matches your workflow.

MethodBest forTime
ssg plugins publishFirst time, or any normal release< 1 minute
Web formOne-off, no CLI handy2 minutes
REST APICI/CD pipelines, scripted releasesAutomatable

All three paths terminate at the same place: a row in the hub's plugins table, which is what ssg plugins install <id> queries.

ssg plugins publish​

The intended happy path. From your plugin project directory:

ssg plugins publish

What it does, in order:

  1. Runs ssg plugins build to make sure the artifact and manifest are fresh
  2. Checks gh CLI auth (errors with a helpful message if you need gh auth login)
  3. Creates github.com/<you>/ssg-plugin-<id> if it doesn't exist (private)
  4. Commits your plugin source and pushes
  5. Creates release v<version> and uploads <id>-<version>.tar.gz + plugin.json as release assets
  6. Opens https://hub.sigmashake.com/submit-plugin?… in your browser with every field pre-filled

The web form is the final step — you click Publish plugin and the row is written. The reason it's a form (rather than the CLI POSTing directly) is so you can review the metadata one more time and tweak the description before it hits the public marketplace.

Flags​

ssg plugins publish --repo=my-org/cool-plugin   # use a non-default repo
ssg plugins publish --no-browser                # print URL, don't open browser

Re-publishing the same version​

ssg plugins publish is idempotent for the GitHub side: if the release tag already exists, it re-uploads the assets with --clobber. The hub side, by contrast, rejects duplicate versions — bump version in plugin.toml before re-publishing.

Publishing a new version​

# 1. Bump version
$EDITOR plugin.toml

# 2. Re-publish
ssg plugins publish

Users uninstall + reinstall to pick up the new version. (Automatic update flow lands in v2.)

Web form​

If you want to host the artifact somewhere other than GitHub Releases (R2, S3, GitLab Releases, etc.) you can submit manually:

  1. Build locally: ssg plugins build
  2. Upload dist/<id>-<version>.tar.gz and dist/plugin.json wherever you want them served from. Constraint: manifest_url must be on raw.githubusercontent.com or hub.sigmashake.com, but artifact_url can point to any HTTPS host.
  3. Open hub.sigmashake.com/submit-plugin
  4. Sign in with GitHub
  5. Fill in the form with the URLs and metadata
  6. Click Publish plugin

The hub will refuse the submission if:

  • The signing fingerprint on the form doesn't match the key registered to your hub account
  • The manifest_url and artifact_url point to different GitHub repos (when using GitHub-hosted artifacts)
  • The id slug is already taken by a different author

REST API​

For CI/CD pipelines:

curl -X POST https://hub.sigmashake.com/api/plugins/submit \
  -H "Authorization: Bearer $GH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-plugin",
    "name": "My Plugin",
    "description": "A short description.",
    "category": "tools",
    "version": "0.1.0",
    "min_ssg_version": "0.29.0",
    "manifest_url": "https://raw.githubusercontent.com/owner/repo/v0.1.0/dist/plugin.json",
    "artifact_url": "https://github.com/owner/repo/releases/download/v0.1.0/my-plugin-0.1.0.tar.gz",
    "artifact_sha256": "<64 hex chars>",
    "signing_fingerprint": "<hex SPKI public key>",
    "repo_url": "https://github.com/owner/repo"
  }'

The Authorization header must be a GitHub personal access token (classic or fine-grained) with public_repo scope. The hub uses this to confirm you have push access to the repository backing the artifact.

Error responses​

StatusMeaning
200Success — response contains hub_url
400Bad payload — see the error field
401Missing or invalid GitHub token
403You don't have push access to the repo, or the signing key doesn't match your account
413Request body > 64 KB
429Rate limit — max 5 submissions/hour/IP

Get the signing fingerprint and SHA-256 in a script​

ARTIFACT="dist/my-plugin-0.1.0.tar.gz"
SHA256=$(shasum -a 256 "$ARTIFACT" | cut -d' ' -f1)
PUBKEY=$(ssg keys show)
SIG=$(printf "%s" "$SHA256" | ssg keys sign)

echo "sha256:      $SHA256"
echo "fingerprint: $PUBKEY"
echo "signature:   $SIG"

These are exactly the same values ssg plugins build writes into dist/plugin.json — you can also just jq -r them out:

jq -r '.artifact_sha256, .signing_fingerprint, .artifact_signature' dist/plugin.json

After publishing​

Once the plugin is live, it's immediately installable from any SSG dashboard:

ssg plugins install my-plugin

Direct URL: https://hub.sigmashake.com/plugin/my-plugin.

Unpublishing​

To remove a plugin from the marketplace, open a support ticket (ssg support --title="Unpublish plugin <id>"). Author-initiated unpublish is honored within one business day. Existing installs continue to work until the user runs ssg plugins uninstall <id> — the hub doesn't push uninstalls to clients.

See also​