Skip to content

docs: replace the empty Pages landing page + artifacthub setup - #319

Open
jordan-simonovski wants to merge 5 commits into
mainfrom
jordansimonovski/pages-landing
Open

jordan-simonovski wants to merge 5 commits into
mainfrom
jordansimonovski/pages-landing

Conversation

@jordan-simonovski

@jordan-simonovski jordan-simonovski commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

clickhouse.github.io/ClickStack-helm-charts has shown "Helm Charts for HyperDX OSS V2 / WIP" since the repo was created, because GitHub Pages renders the gh-pages README and nothing ever updated it. The landing page now explains what ClickStack is, how to install both charts, and where the docs, upgrade guide and releases live.

  • The page source is pages/ on main, so edits go through review. The last step of the release job copies it onto gh-pages and commits only when something changed.
  • Charts are unaffected. The step only adds or overwrites README.md and _config.yml, and runs after chart-releaser in the same serialised job, so it can't race index.yaml updates.
  • The page names no versions and uses absolute links, so it doesn't need editing per release.

Residual risks, not handled here:

  • Jekyll renders the page with Liquid. A stray {{ or {% in a future pages/ edit would fail the Pages build, which also stops new index.yaml updates from deploying until fixed. A PR-time Jekyll build would catch it if pages/ grows.
  • Deleting a file from pages/ doesn't delete it from gh-pages.

Also sets up the Artifact Hub listing under the ClickHouse org:

  • pages/artifacthub-repo.yml links this repo to the org, which gives both charts the verified publisher badge.
  • Both charts' metadata now points at this repo instead of hyperdxio/helm-charts, and adds the icon, keywords and category Artifact Hub shows.
  • clickstack-operators goes to 1.1.1, because the release script only bumps clickstack and chart-releaser skips existing versions. Without the bump, the operators metadata would never be published.
Testing

Against a bare clone of this repo: the first run committed README.md and _config.yml beside index.yaml and charts/, and the second run was a no-op. Every link on the page returns 200. The real push from the runner and the Pages rebuild happen on the first release run after merge.

The site at clickhouse.github.io/ClickStack-helm-charts showed the gh-pages
README from the initial commit. The page now lives in pages/ on main and the
release job copies it onto gh-pages, committing only when it changed.
@jordan-simonovski
jordan-simonovski requested a review from a team as a code owner November 17, 2026 00:16
@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 95edf90

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
helm-charts Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

Helm template coverage

Metric Value
Line coverage 99.85%
Branch coverage 91.00%
Line threshold 99% (met)
Branch threshold 90% (met)
Uncovered details

charts/clickstack/templates/NOTES.txt

Uncovered lines: none

Uncovered branches: 37:default:fallback

charts/clickstack/templates/_helpers.tpl

Uncovered lines: 17

Uncovered branches: 130:range:empty, 132:range:empty, 133:ternary:false, 16:if:true, 194:or(1):true, 211:range:empty, 242:default:fallback, 243:or(1):true, 259:if:false, 327:range:empty, 348:range:empty

charts/clickstack/templates/additional-manifests.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/clickhouse/cluster.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/clickhouse/keeper.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/configmap.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/cronjob-check-alerts.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/dashboard-configmap.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/dashboard-provisioner-rbac.yaml

Uncovered lines: none

Uncovered branches: 40:range:empty

charts/clickstack/templates/hyperdx/deployment.yaml

Uncovered lines: none

Uncovered branches: 121:default:fallback, 131:default:fallback, 196:default:fallback, 201:with:empty, 20:with:empty, 26:default:fallback, 41:if:false, 42:with:empty

charts/clickstack/templates/hyperdx/hpa.yaml

Uncovered lines: none

Uncovered branches: 16:with:empty

charts/clickstack/templates/hyperdx/ingress.yaml

Uncovered lines: none

Uncovered branches: 35:if:false, 40:range:empty, 45:range:empty, 48:with:empty, 54:range:empty, 58:range:empty, 59:or(2):true, 59:or(3):true

charts/clickstack/templates/hyperdx/networkpolicy.yaml

Uncovered lines: none

Uncovered branches: 11:with:empty

charts/clickstack/templates/hyperdx/pdb.yaml

Uncovered lines: none

Uncovered branches: 10:with:empty

charts/clickstack/templates/hyperdx/secret.yaml

Uncovered lines: none

Uncovered branches: 1:or(2):true, 1:or(3):true

charts/clickstack/templates/hyperdx/service.yaml

Uncovered lines: none

Uncovered branches: 14:default:fallback, 9:with:empty

charts/clickstack/templates/hyperdx/serviceaccount.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/mongodb/community.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/mongodb/password-secret.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/otel-collector/custom-config.yaml

Uncovered lines: none

Uncovered branches: none

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found. This PR is docs, chart metadata, and one CI workflow step — no Helm templates or render paths change, the two version bumps are internally consistent, and the one hard-fail path in the new workflow step (gh-pages missing) is unreachable because that branch already backs the live Pages site. Recommended and nit-level items below.

🟡 P2 — recommended

  • charts/clickstack/Chart.yaml:7, charts/clickstack-operators/Chart.yaml:7 — the icon URL pins to hyperdxio/hyperdx@main, a moving ref duplicated in both charts, so an upstream rename or move silently 404s the icon on Artifact Hub with nothing in CI to catch it.
    • Fix: Pin the icon to an immutable tag or commit SHA, or host the SVG in this repo and reference a stable path.
    • maintainability, testing, project-standards
🔵 P3 nitpicks (5)
  • .github/workflows/release.yml:90 — cp -R pages/. followed by git add -A only ever stages additions and modifications, so a file later removed from pages/ is never deleted from gh-pages.

    • Fix: If a true mirror is intended, clear prior landing-page files before copying (scoped so chart-releaser's index.yaml and *.tgz are untouched); otherwise document the additive-only behavior.
    • correctness, maintainability, reliability
  • .github/workflows/release.yml:82 — the Sync step lacks the if: steps.changesets.outputs.hasChangesets == 'false' guard that the chart-releaser and GHCR steps carry, so it also runs on changeset-accumulation pushes; behavior is idempotent and likely intended but decouples Pages publishing from release gating.

    • Fix: Confirm the unguarded run is deliberate, or add the same if: condition for consistency.
    • correctness, reliability, maintainability
  • charts/clickstack-operators/README.md.gotmpl:7 — the operators chart gains a sources: list in Chart.yaml, but its gotmpl never renders {{ template "chart.sourcesSection" . }} the way the clickstack gotmpl does, so the new source link is absent from the generated operators README.

    • Fix: Add the chart.sourcesSection template to the operators gotmpl for parity.
    • maintainability, project-standards
  • README.md:3 — the Artifact Hub and Build Status badges are hand-added to the root README, which make docs does not regenerate (helm-docs only scans charts/), so these badges can drift from the gotmpl-generated chart READMEs.

    • Fix: Note that the root README is hand-maintained, or add a check that the shared badge markup stays in sync across all three files.
  • scripts/update-chart-versions.js:6 — the operators 1.1.0 → 1.1.1 bump is manual because the version script only rewrites ./charts/clickstack, an implicit coupling that CI would not catch if a future operators change forgot to bump.

    • Fix: Document in AGENTS.md/contributing notes that clickstack-operators/Chart.yaml must be hand-bumped, since changesets do not touch it.

Reviewers (6): correctness, project-standards, reliability, security, maintainability, testing.

The two prior PR comments are automated bot output (changeset-bot, helm template coverage) with no human feedback to verify, so the previous-comments reviewer was not run.

Testing gaps:

  • The new Sync-Pages step is only exercised on the first post-merge release; CI covers it statically via actionlint/zizmor but there is no dry-run of the fetch/worktree/commit/push path (including the first-run case and a non-fast-forward push with no retry).
  • Nothing validates that the icon, artifacthub.io/links, and artifacthub.io/category values resolve or match Artifact Hub's accepted schema; an invalid category or moved asset would surface only at ingestion time.
  • Chart.yaml metadata changes have no helm-unittest assertions — expected, since helm-unittest validates rendered templates rather than chart metadata.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR.

Links the chart repo to the ClickHouse org on Artifact Hub so both
charts get the verified publisher badge.
…Artifact Hub

Adds an icon, keywords and Artifact Hub category to both charts and
replaces the old hyperdxio/helm-charts source links. Bumps
clickstack-operators to 1.1.1 so the new metadata gets published.
@jordan-simonovski jordan-simonovski changed the title docs: replace the empty Pages landing page docs: replace the empty Pages landing page + artifacthub setup Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant