Contributing to KubeStellar Console Marketplace

Thank you for contributing! This guide explains how to submit dashboards, card presets, and themes to the community marketplace.

Quick Start

Fork this repository
Add your content (dashboard, card preset, or theme)
Add an entry to registry.json
Open a pull request

Submitting a Dashboard

Step 1: Export Your Dashboard

Open KubeStellar Console
Navigate to the dashboard you want to share
Click the floating action button (bottom-right)
Click Export — a JSON file will download

Step 2: Create Your Submission

Create a new directory under dashboards/ with a kebab-case name:
```
dashboards/my-awesome-dashboard/dashboard.json
```
(Optional, but strongly recommended) Add a PNG screenshot as screenshot.png (recommended: 1200x630). Screenshots are not required by CI, but they help reviewers confirm what the dashboard should look like before they import it.

Step 3: Add to Registry

Add an entry to registry.json:

{
  "id": "my-awesome-dashboard",
  "name": "My Awesome Dashboard",
  "description": "A brief description of what this dashboard shows.",
  "author": "your-github-username",
  "version": "1.0.0",
  "downloadUrl": "https://raw.githubusercontent.com/kubestellar/console-marketplace/main/dashboards/my-awesome-dashboard/dashboard.json",
  "tags": ["monitoring", "production"],
  "cardCount": 6,
  "type": "dashboard"
}

Before opening a PR, validate that your registry.json change is well-formed and that the entry fields line up with the file you added:

python3 -m json.tool registry.json > /dev/null
python3 scripts/validate-marketplace.py --mode static

Submitting a Card Preset

Card presets add a single card to the user's current dashboard.

Step 1: Create the Preset JSON

Create a file under card-presets/:

{
  "format": "kc-card-preset-v1",
  "card_type": "pod_issues",
  "title": "Pod Health Monitor",
  "config": {}
}

The card_type must be one of the 153 available types — see Available Card Types in the README.

Step 2: Add to Registry

{
  "id": "pod-health-monitor",
  "name": "Pod Health Monitor",
  "description": "Card showing pods with issues like CrashLoopBackOff and OOMKilled.",
  "author": "your-github-username",
  "version": "1.0.0",
  "downloadUrl": "https://raw.githubusercontent.com/kubestellar/console-marketplace/main/card-presets/pod-health-monitor.json",
  "tags": ["monitoring", "pods"],
  "cardCount": 1,
  "type": "card-preset"
}

Submitting a Theme

Themes change the entire look and feel of the console.

Step 1: Create the Theme JSON

Create a file under themes/. Your theme must follow the Console Theme interface. See themes/midnight-blue.json for a complete example.

Key fields:

id: Unique kebab-case identifier
name: Display name
dark: true for dark themes, false for light
colors: All color tokens (HSL for core, hex for brand/status/chart)
font: Font family and weight definitions

Step 2: Add to Registry

Include themeColors for the preview dots shown in the marketplace:

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "A custom theme with warm tones.",
  "author": "your-github-username",
  "version": "1.0.0",
  "downloadUrl": "https://raw.githubusercontent.com/kubestellar/console-marketplace/main/themes/my-theme.json",
  "tags": ["dark", "warm"],
  "cardCount": 0,
  "type": "theme",
  "themeColors": ["#f59e0b", "#f97316", "#ef4444", "#10b981", "#06b6d4"]
}

Testing Your Submission Locally

Marketplace contributions are config-only, but you should still validate them before opening a PR.

Prerequisites

Python 3 (Python 3.6+ recommended) — the marketplace validator uses only standard library modules, no pip dependencies required
Git
A local checkout of kubestellar/console for --mode cross-repo, local Marketplace UI testing, and TypeScript unit tests
Node.js 22.x when working with the Console checkout (matches the current Console dev/CI environment)

Recommended sibling checkouts for cross-repo work

Keeping the Console and Marketplace repos next to each other makes the validator paths, local UI testing, and TypeScript unit test commands below easier to follow:

cd ..
git clone https://github.com/kubestellar/console.git console
# console-marketplace should already be checked out beside it

cd console
cd web && npm install && cd ..

# Start a local Console for end-to-end Marketplace testing
./start-dev.sh
# or, if you want GitHub OAuth plus Vite HMR:
./startup-oauth.sh --dev

The local Console uses backend http://localhost:8080, frontend http://localhost:5174, and kc-agent http://localhost:8585. Wait for the Console to finish starting before you begin the integration checks below.

1. Run the repository checks locally

From the repository root:

python3 -m json.tool registry.json > /dev/null
python3 scripts/validate-marketplace.py --mode static
python3 scripts/validate-marketplace.py --mode cross-repo --console-path /path/to/console

Important: The CI Marketplace Quality Gate workflow runs validate-marketplace.py --mode static on every PR. Running it locally before you push will catch issues early and prevent surprising CI failures.

What these checks catch:

python3 -m json.tool: malformed JSON
--mode static: registry consistency, naming, dashboard grid/shape checks, required fields (matches CI behavior)
--mode cross-repo: everything in static, plus validation that referenced card_type values exist in a local kubestellar/console checkout

If you only changed one file, you can also validate it directly:

python3 -m json.tool dashboards/<id>/dashboard.json > /dev/null
python3 -m json.tool card-presets/<id>.json > /dev/null
python3 -m json.tool themes/<id>.json > /dev/null

2. Test a submission in isolation

Dashboards

Validate the exported file before wiring it into registry.json:

python3 -m json.tool dashboards/<id>/dashboard.json > /dev/null
python3 - <<'PY'
import json
with open('dashboards/<id>/dashboard.json') as f:
    data = json.load(f)
assert data['format'] == 'kc-dashboard-v1'
assert isinstance(data.get('cards'), list) and data['cards']
for card in data['cards']:
    assert card.get('card_type')
    assert isinstance(card.get('position'), dict)
print('dashboard.json looks valid')
PY

A dashboard card_type is valid only when it matches a real Console card ID in snake_case. The authoritative list is in README.md#available-card-types-153, and the safest verification is the cross-repo validator:

python3 scripts/validate-marketplace.py --mode cross-repo --console-path /path/to/console

Card presets

Make sure the preset uses kc-card-preset-v1 and references a real Console card type:

python3 -m json.tool card-presets/<id>.json > /dev/null
python3 scripts/validate-marketplace.py --mode cross-repo --console-path /path/to/console

If you already have a local Console running, you can test the preset without publishing it by pasting this into the browser DevTools console on a dashboard page:

window.dispatchEvent(new CustomEvent('kc-add-card-from-marketplace', {
  detail: await (await fetch('http://localhost:8000/card-presets/<id>.json')).json()
}))

Themes

Validate the JSON, then preview it in a local Console by loading it into custom theme storage:

const theme = await (await fetch('http://localhost:8000/themes/<id>.json')).json()
localStorage.setItem('kc-custom-themes', JSON.stringify([theme]))
window.dispatchEvent(new Event('kc-custom-themes-changed'))

After that, open Settings → Theme and select your theme.

3. Test integration with a local Console

Use a local checkout of kubestellar/console for end-to-end verification.

Serve this repository locally:
```
python3 -m http.server 8000
```
If you have not prepared the Console checkout yet, follow the setup steps in Recommended sibling checkouts for cross-repo work, then wait for the Console to come up at http://localhost:8080.
The Console marketplace currently fetches the registry from a hard-coded URL in web/src/hooks/useMarketplace/demoData.ts; there is no runtime env var/dev flag for overriding it yet.
In your Console checkout, temporarily point REGISTRY_URL at your local server by editing web/src/hooks/useMarketplace/demoData.ts:
```
const REGISTRY_URL = 'http://localhost:8000/registry.json'
```
Reload the Console, open Marketplace, and install your dashboard, card preset, or theme.
For dashboards, also test the same JSON through the normal dashboard import flow in the running Console (floating action button → Import) and verify the layout and cards render correctly.
When you are done testing, revert the temporary override before you commit anything in the Console repo:
```
cd /path/to/console
git restore web/src/hooks/useMarketplace/demoData.ts
git status --short
```

If you want to keep the override around for a later test session without risking an accidental Console commit, stash just that file:

cd /path/to/console
git stash push -m "local marketplace registry override" -- web/src/hooks/useMarketplace/demoData.ts

You can also test a dashboard import directly against a running local Console:

await fetch('/api/dashboards/import', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(await (await fetch('http://localhost:8000/dashboards/<id>/dashboard.json')).json())
})

4. Run TypeScript unit tests when changing `web/src/**`

PRs that touch web/src/** (plus vitest.marketplace.config.ts or .github/workflows/ts-unit-tests.yml) run the TypeScript Unit Tests workflow. Those tests reuse shared Vitest/Vite config and npm dependencies from kubestellar/console, so you need a local Console checkout even though the tests live in this repo.

The CI workflow uses a sparse Console checkout; for local work, a normal sibling checkout is simpler. If you followed the layout above, this is the local equivalent of CI:

# one-time shared dependency install in the Console checkout
cd ../console/web
npm ci

# one-time symlink so Marketplace tests resolve shared deps from the Console checkout
cd ../..
ln -sfn "$(pwd)/console/web/node_modules" console-marketplace/web/node_modules

# run Marketplace TypeScript unit tests
cd console/web
npx vitest run \
  --config ../../console-marketplace/vitest.marketplace.config.ts \
  --dir ../../console-marketplace/web

Marketplace TypeScript unit tests live under web/src/** (including web/src/**/__tests__/**). Re-run the command above whenever you change marketplace TypeScript source or tests there.

5. Manual verification checklist

Before submitting, verify the following in a running Console:

Dashboards: imports successfully, card layout is preserved, cards render without errors
Card presets: install into an existing dashboard, title/config are applied, card renders without errors
Themes: colors are readable in the sidebar, dashboard cards, Marketplace tiles, and Settings page
Themes: capture screenshots of the key surfaces you changed (at minimum: dashboard view, Marketplace, and Settings → Theme)
Themes: if your theme is light, confirm text contrast on light backgrounds; if dark, confirm contrast on dark cards and panels

6. CI requirements for pull requests

PRs that touch registry.json, dashboards/**, presets/**, card-presets/**, themes/**, or scripts/** trigger CI validation.

Current checks include:

Validate JSON (.github/workflows/validate-json.yml)
Marketplace Quality Gate (.github/workflows/marketplace-quality.yml)
PR Verifier (.github/workflows/pr-verifier.yml)

Run the local validation commands above before you open the PR so CI findings are limited to genuine review issues.

Guidelines

Quality

Descriptive name: Choose a clear name
Good description: 1-2 sentences explaining what it does and who it's for
Relevant tags: Use existing tags when possible
Tested: Make sure your content works when installed into a fresh console

Tag	Use for
`sre`	Site reliability / operations
`security`	Security monitoring and auditing
`compliance`	Compliance and governance
`monitoring`	General observability
`production`	Production focused
`development`	Dev/staging focused
`gitops`	GitOps and pipelines
`networking`	Network monitoring
`storage`	Storage and PV monitoring
`cost`	Cost management
`gpu`	GPU and ML workloads
`helm`	Helm release management
`rbac`	Access control
`dark`	Dark themes
`warm`	Warm color palette themes
`minimal`	Clean, minimal design

Versioning

Start at 1.0.0
Patch: layout tweaks, typo fixes
Minor: new cards, significant changes
Major: complete redesigns

Pull Request Title

Use this format:

Add <name> dashboard
Add <name> card preset
Add <name> theme

Code of Conduct

This project follows the KubeStellar Code of Conduct.

Questions?

Open an issue
Join the KubeStellar community

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Contributing to KubeStellar Console Marketplace

Quick Start

Submitting a Dashboard

Step 1: Export Your Dashboard

Step 2: Create Your Submission

Step 3: Add to Registry

Submitting a Card Preset

Step 1: Create the Preset JSON

Step 2: Add to Registry

Submitting a Theme

Step 1: Create the Theme JSON

Step 2: Add to Registry

Testing Your Submission Locally

Prerequisites

Recommended sibling checkouts for cross-repo work

1. Run the repository checks locally

2. Test a submission in isolation

Dashboards

Card presets

Themes

3. Test integration with a local Console

4. Run TypeScript unit tests when changing `web/src/**`

5. Manual verification checklist

6. CI requirements for pull requests

Guidelines

Quality

Tags

Versioning

Pull Request Title

Code of Conduct

Questions?

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to KubeStellar Console Marketplace

Quick Start

Submitting a Dashboard

Step 1: Export Your Dashboard

Step 2: Create Your Submission

Step 3: Add to Registry

Submitting a Card Preset

Step 1: Create the Preset JSON

Step 2: Add to Registry

Submitting a Theme

Step 1: Create the Theme JSON

Step 2: Add to Registry

Testing Your Submission Locally

Prerequisites

Recommended sibling checkouts for cross-repo work

1. Run the repository checks locally

2. Test a submission in isolation

Dashboards

Card presets

Themes

3. Test integration with a local Console

4. Run TypeScript unit tests when changing web/src/**

5. Manual verification checklist

6. CI requirements for pull requests

Guidelines

Quality

Tags

Versioning

Pull Request Title

Code of Conduct

Questions?

4. Run TypeScript unit tests when changing `web/src/**`