Add Charts to Artifacthub

[weatherhog]

As a Giant Swarm engineer, I want to publish our Helm charts to Artifact Hub so that our customers and the open-source community can easily discover, verify, and deploy our solutions.

---

Status (2026-07-21)

Paused at a one-chart pilot; ready to scale on an opt-in basis.

• Live on Artifact Hub: hello-world only, as Verified Publisher. (A full 264-chart backfill was run and verified on 2026-07-16, then deliberately rolled back the same day — see history in section B.)
• Design settled: publication is opt-in per repository, driven by a nightly reconciler that now lives in giantswarm/github.
• Blocking the rollout: (A) a shared Artifact Hub account + secrets, and (B) merging the reconciler PR giantswarm/github#5659.

Why

• Discoverability & trust: Artifact Hub is the de-facto search surface for Helm charts. A curated, Verified Publisher presence increases adoption and signals maintenance quality.
• Defensive namespace ownership: in 2023 a third party listed our public catalogs on Artifact Hub under our name (no READMEs, indexing errors, implied support). We now control the giantswarm Artifact Hub organization.

Approach

• OCI-first from gsoci.azurecr.io/charts/giantswarm (aligned with the HelmRelease/OCIRepository migration, giantswarm/giantswarm#34515). GitHub-Pages catalogs are deliberately not registered (legacy path).
• Opt-in per repository: a team sets artifactHub: true on its repo entry in giantswarm/github repositories/team-*.yaml; only flagged charts are published. The flag replaces the earlier "publish all + denylist" idea and is itself the staged-rollout control.
• Reconciler-only (no per-release CI step): a nightly job resolves each flagged repo to its chart name via the catalog's giantswarm.io/helmcharts annotation, then registers/deregisters against the Artifact Hub org. private-tagged components are never published. After first registration, Artifact Hub polls the registry itself, so new chart versions need no involvement.

Work items

A. Shared account (workstream A — the main prerequisite)

• Google group artifacthub@giantswarm.io — no Workspace bot user needed; AH signup only needs an email that receives the verification link (group must accept external mail).
• Sign up on artifacthub.io with email+password (a group can't use OAuth); store credentials in the shared Honey Badger 1Password vault.
• Invite the account to the giantswarm AH org and create an API key under it (replaces the personal key used for the PoC).
• Add four repo secrets on giantswarm/github (needs Planeteers): ARTIFACTHUB_API_KEY_ID, ARTIFACTHUB_API_KEY_SECRET, ACR_GSOCI_USERNAME, ACR_GSOCI_PASSWORD.

B. Reconciler — giantswarm/github#5659 (open)

• artifactHub schema flag + nightly artifacthub-sync workflow + tools/artifacthub/reconcile.py.
• Proven mechanics carried over verbatim: register disabled: true → ORAS-push metadata artifact → enable; dev-version ignore rules; CloudFront cache-bust; ~1 req/s throttle.
• Guardrails: abort on an empty opt-in set or empty gsoci listing; deregistration capped at max(10, 10%) per run; manual runs default to dry-run with a LIMIT input for tranches.
• Inert until the secrets exist (the workflow no-ops with a notice), so it is safe to merge ahead of workstream A. hello-world-app is flagged in the PR, so the pilot continues; a live dry-run shows zero diff.
• History: the standalone repo giantswarm/artifacthub-sync ran the full 264-chart backfill (all verified) on 2026-07-16, rolled back the same day to the hello-world pilot — publishing everything is an org-level step the team gates explicitly. Its improvements (LIMIT, cache-bust, strict-JSON parsing) are ported into giantswarm/github#5659; giantswarm/artifacthub-sync#4 and giantswarm/github#5653 are closed, and the standalone repo is archived (2026-07-17).

C. Package-time metadata — giantswarm/app-build-suite#569 (open)

• When missing in the chart, abs injects at packaging: artifacthub.io/license (from the repo LICENSE), artifacthub.io/links (Support → repo issues; Upstream from sources:), and a chart-dir README.md (copied from the repo root). Explicit Chart.yaml values always win, and nothing injected is visible outside Artifact Hub, so it is harmless for non-published charts.
• Icon decision revised (2026-07-21): the forced GS-logo icon override was dropped. It was a child of the publish-all strategy; with opt-in publishing it would have rebranded every abs-built chart in Backstage/happa for zero AH benefit. Charts keep their own icons; a team sets icon: in Chart.yaml when opting in if it wants one. Remaining review point: Support links point to <repo>/issues, which is dead for repos with GitHub issues disabled.

D. Scaffold — giantswarm/template-app#65 (open)

• Add artifacthub.io/license + artifacthub.io/links to helm/{APP-NAME}/Chart.yaml so new charts are born compliant.

E. Cleanup — giantswarm/external-dns-app#470 (open)

• Maintainers stripped, ready for merge + patch-release (also fixes its verified/dev-filter state).

Rollout sequence (once A + giantswarm/github#5659 merge)

1. The nightly reconcile covers the flagged pilot (hello-world) — zero-diff steady state.
2. Teams flag their repos (artifactHub: true) at their own pace; each nightly run registers the delta. Tranche size is controlled by ordinary PR review of the flag changes; LIMIT remains available as a brake.
3. Pilot validation after giantswarm/app-build-suite#569 merges and hello-world releases: confirm license / links / README render on the AH page.

Key learnings (from the PoC, 2026-07-15)

• Zero CI work per release: Artifact Hub polls the OCI registry itself, so new versions appear automatically. The metadata artifact is static per chart; the only recurring task is registering new charts.
• Sequencing matters: AH's first tracker pass must already see the metadata artifact (register disabled: true → push artifact → enable). external-dns-app missed that window in the PoC and stayed unverified until its next release forced a reprocess.
• Dev-tag pollution: X.Y.Z-dev.… tags share the OCI path and can headline the listing; filtered per chart via ignore: [{name: <chart>, version: ".*-dev\\..*"}] in artifacthub-repo.yml.
• Verified Publisher works via the ORAS-pushed artifacthub-repo.yml — confirmed on hello-world after its v3.0.3 release (giantswarm/hello-world-app#262).
• Maintainers: intentionally not used — AH only renders them with an email; the org page + Verified badge + Support link cover it.
• API gotchas: no AH service accounts exist (keys are user-bound → shared account needed); always send BOTH X-API-KEY-ID and X-API-KEY-SECRET headers, else a misleading CSRF 403 ("referer not supplied").

Accepted risks

• Unknown co-owner(s) of the AH org — resolved: owner identified (2026-07-16).
• giantswarm-<chart> AH repo-name collisions with third-party repos → 409s logged for manual review.
• New charts appear on AH within the cron interval (≤1 day after flagging), not instantly.

Related: giantswarm/roadmap#2427 (Planeteers) — proposing to consolidate here.

[weatherhog]

Phase 1 update — the Artifact Hub org giantswarm already exists ✅/⚠️

GET https://artifacthub.io/api/v1/orgs/giantswarm returns:

• display name: Giant Swarm, home: giantswarm.io, proper description and logo

So we don't create an org — we need to find who controls it and get team members + a bot account invited. Candidates to ask (in this order):

1. Lutz Lange — presales-demos uses ARTIFACTHUB_API_KEY_ID/SECRET (scripts/artifacthub-catch.py), so he has an AH account
2. Timo — long-standing Artifact Hub advocate (#area-platform threads)
3. Joe / Marcus — handled the 2023 third-party-listing episode

If it turns out nobody at Giant Swarm controls it, we open an issue with the Artifact Hub team (github.com/artifacthub/hub) to reclaim the name — we can prove we own the GitHub org and domain.

Remaining manual steps once access is sorted (everything after this is API-automatable):

1. Team members sign in at artifacthub.io (GitHub/Google OAuth or email) and get invited via Control Panel → org → Members
2. Create/invite a bot account with a team-controlled email for CI (personal accounts shouldn't hold the CI key)
3. Bot account: Control Panel → Settings → API keys → Add → capture X-API-KEY-ID + secret (shown once)
4. Store in 1Password + add to the CircleCI architect context

[weatherhog]

Phase 1 update 2 — asked around internally: nobody at Giant Swarm knows who owns the existing giantswarm Artifact Hub org (it has our exact branding/logo but publishes zero packages).

Next step: reclaim it via the Artifact Hub maintainers (cncf-artifacthub-maintainers@lists.cncf.io). There is direct precedent that they handle this quickly:

• artifacthub/hub discussion #4598 ("Reclaim org access") — maintainer helped same-day via email
• [ABUSE-REPORT] CNCF org artifacthub/hub#3820 (CNCF brandjacking) — org suspended, renamed, and the name reserved for the rightful owner

Plan: create an AH account with a giantswarm.io identity first (needed as the transfer target + proof of affiliation), then email the maintainers offering standard ownership proof (DNS TXT / site file / GitHub org). Lucas is on it.

[weatherhog]

Rollout landed 🎉 All 264 public Giant Swarm charts are now on Artifact Hub under the giantswarm org with the Verified Publisher badge: https://artifacthub.io/packages/search?org=giantswarm

Dev pre-release versions are filtered per chart via artifacthub-repo.yml ignore rules. Ongoing maintenance (new charts, orphan cleanup) is the daily reconciler in https://github.com/giantswarm/artifacthub-sync — it only needs its four repo secrets once the bot account exists (workstream A, deliberately last).

In review: app-build-suite#569 (metadata injection at package time), template-app#65 (scaffold annotations), artifacthub-sync#4 (LIMIT + cache-bust fix), github#5653 (ownership), external-dns-app#470 (drop maintainers).

Notes: artifacthub.io's API sits behind CloudFront with a 1h cache on GETs (reconciler cache-busts now); the one-time backfill burst tripped ACR's rate limit on AH's cosign signature checks for 79 repos — indexing/verification unaffected, badges self-heal on next chart release.

[weatherhog]

Scope correction: rolled the rollout back to a hello-world-only pilot — 263 registrations deleted (0 failures), only hello-world remains (still Verified Publisher). The artifacthub-sync reconcile workflow is disabled so nothing re-registers automatically.

The full-rollout mechanism stays proven and ready; re-enabling is: team go on scope (denylist?) + icon policy (app-build-suite#569 review) + bot account/secrets (workstream A) → re-enable workflow → dry-run → LIMIT tranche → team confirm → full run.