Skip to content

✨ dashboard: onboarding and GitHub App errors point to the Getting Started guide - #15774

Merged
clubanderson merged 3 commits into
v5from
feat/onboarding-errors-open-guide
Oct 30, 2026
Merged

clubanderson merged 3 commits into
v5from
feat/onboarding-errors-open-guide

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Closes #15772

A new GHE operator saw GitHub App permission issue: GitHub App 5686 has no installation for this org — install it … and had to ask Slack for next steps, the install URL, and where the welcome checklist / Governor Config were. The dashboard now answers that itself.

What changes

Server (pkg/dashboard/onboarding.go)

  • ClassifyOnboardingMessage(msg) — table of message → kind + guideStep (GitHub App not installed / wrong installation / permissions / credentials, GHES base URL, repo target, no projects, no agents, proxy token). Message text is never altered.
  • StatusPayload.onboardingIssues[] {kind, guideStep, message} derived after the GitHub App / repo-target fields are final; SystemAlert.onboarding/guideStep set in AddSystemAlert; deepHealth checks github_auth / repo_target (and /health) carry onboarding: true, guideStep.

SPA

  • Guide tip “New hive? Open the 🧭 Guide (top navbar) → step ‘Install the Forge App (GitHub App)’ for the install URL and permissions checklist.” appended to the GitHub App banner (all branches incl. operator-side), the repo-target banner (with a note on what gates ⚙️ Governor Config: non-read role), onboarding system-alert rows, and the health-pill tooltip lines.
  • openWelcomeDialog(stepId) expands + scrolls to a step; the tip link uses it.
  • 🧭 Guide chip and sidebar entry are forced visible while any onboardingIssues is active, even after the checklist was dismissed (read-only role stays gated).
  • The guide's GitHub App step now prints the concrete install URL for the configured host (githubAppInstallURL, GHES-aware); on an enterprise host with no slug it says what to configure instead of pointing at github.com.
  • Hub timeline github_app_changed rows get the same pointer.

Governor Config missing for the operator: not a bug — the Guide, its entry points and the settings gear all require a non-read role from /api/role. The tip and docs now say so.

Tests: onboarding_test.go (classifier table, kind→step, onboardingIssuesFor states, status payload + deep-health JSON, system-alert classification). Docs: operator-reference, getting-started; changelog fragment.

Screenshots (local run against the hive spoke with a faked not-installed GHE state)

GitHub App banner + system alert with the guide tip; Guide chip visible in the navbar:

GitHub App banner and system alert carrying the Open the Guide tip

Clicking the tip opens the guide at the GitHub App step with the concrete github.ibm.com install URL:

Getting Started guide opened at the GitHub App step showing the GHES install URL

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 30, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Oct 30, 2026
@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#15859 ✨ feature: add abandoned counts to contributor leaderboards same files src/pkg/dashboard/static/index.html
#15863 ✨ feature: show abandoned counts on contributor cards and status CONFLICT src/docs/api-reference/dashboard-misc.md
#15866 ✨ Animate live tracker, contributor and Knowledge count deltas same files src/pkg/dashboard/static/index.html
#15871 🐛 fix: stage tracker gives immediate Let-hive-decide feedback and says why a human is wanted same files src/pkg/dashboard/static/index.html
#15849 ✨ Show online ClankeR IDs on the Contributors count pill CONFLICT src/docs/api-reference/dashboard-misc.md
#15854 🐛 fix: preserve merge notifications across reloads and show countdown same files src/pkg/dashboard/static/index.html
#15853 ✨ Complete native GitHub queue CI and policy integration same files src/pkg/dashboard/static/index.html
#15876 🐛 Fold hive PR notes into one edited status comment and stop no-findings review spam same files src/docs/operator-reference.md
#15804 ✨ Show the upgrade animation for every roll (announce + SIGTERM fallback) CONFLICT src/docs/api-reference/auth.md
src/docs/api-reference/dashboard-misc.md
src/docs/api-reference/health-status-events.md
src/docs/api-reference/snapshots-and-style.md
#15731 📖 docs: split the operator reference CONFLICT src/docs/operator-reference.md
#15834 ✨ stage tracker: PR sub-row names the other issues it also closes same files src/pkg/dashboard/static/index.html
#15757 ✨ Auto-merge hive-authored superseding PRs without operator decision same files src/docs/operator-reference.md

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 30, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission → 050-review-pending: required-check-pending:build-and-test

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • test (rest 3/4)

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One concrete blocker, plus a note on the other red checks.

src/pkg/dashboard/static/index.html is generated, and this PR edits it directly. TestIndexHTMLIsGenerated (src/pkg/dashboard/webstatic/indexgen_test.go:20-29) rebuilds index.html from static-src/ via ConcatIndex and fails if the committed file differs. The diff touches static/index.html but no file under static-src/, so the test fails deterministically — it did on test (rest 3/4) three times in run 41068242534 with: "static/index.html differs from the concatenation of static-src/ … Edit the per-area sources in static-src/, then run make dashboard-gen (go generate ./pkg/dashboard/webstatic/) and commit both." Fix: move the WELCOME_STEPS/onboarding edits into the owning static-src/ file(s), run make dashboard-gen, and commit both. The Go side (onboarding.go ClassifyOnboardingMessage / onboardingKindGuideStep) is unaffected by this.

Not this diff's fault: golangci-lint died fetching the action (Unexpected HTTP response: 500) and coverage fails downstream of the test shard, so both should clear once the shard is green. The conflicts-with-open-pr label is a separate rebase question for whoever lands first.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Go side reads correctly to me — onboardingIssuesFor is pure and runs after the GitHub App / repo-target fields are final in UpdateStatusIfFresh (server.go:2696-2702), and the body matches the diff. Two things in the diff itself break CI, and one red check is not yours:

  1. static/index.html is generated (src/pkg/dashboard/webstatic/indexgen_test.go:15-29): TestIndexHTMLIsGenerated concatenates static-src/ and compares byte-for-byte. This PR edits the output (src/pkg/dashboard/static/index.html, +105/-?) and touches nothing under static-src/, so test (rest 3/4) fails with "first difference at line 1193, byte 7". Move the SPA edits into the matching static-src/ area, run make dashboard-gen, commit both.
  2. Style ratchet (style_ratchet_test.go:88): your change drops inline style= attributes on the operator page from 1427 to 1425, which is good, but the ratchet requires lowering styleRatchetBaselines["operator static/index.html"].inlineStyles to 1425 so it keeps biting.
  3. golangci-lint is an infrastructure failure (action download returned HTTP 500 at golangci-lint-action setup, job 124106209522) — re-run, not a diff problem. coverage is only red because the rest shard failed.

Open question, not a finding: onboardingIssuesFor emits no-agents whenever cfg != nil && len(status.Agents) == 0 (onboarding.go:171). If any status update can arrive before the agent list is populated, a fresh hive would briefly show the "add an agent" tip; worth a glance at the first-publish path if that matters to you.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

hive/ci-report (scanner): three distinct causes at ccb4968.

  1. test (rest 3/4) — TestIndexHTMLIsGenerated (job 124106582368): static/index.html differs from the concatenation of static-src/ (first difference at line 1193, byte 7). Re-run make dashboard-gen (go generate ./pkg/dashboard/webstatic/) and commit both the static-src/ edit and the regenerated static/index.html. coverage is red only downstream of this shard.
  2. golangci-lint — Unexpected HTTP response: 500 from the action's download step (job 124106209522): infrastructure, not this diff; it will clear on the next push.
  3. The PR is dirty against v5 (overlap check says it conflicts with v5 itself) — needs a rebase/merge of v5 before it can merge.

No push from the hive on an author-owned branch; a new head re-runs everything.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 30, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission: no activity for 30m0s: merge-train:queued-behind#15748:2/9:0/0:main.go,main_sweeps.go,auth.md,dashboard-misc.md,+14

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission → 050-review-pending: check-pending

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission → 050-review-pending: required-check-pending:Sign-off survives the squash

@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission → 050-review-pending: required-check-pending:build-and-test

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

  • the branch conflicts with the base and needs a rebase

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

…arted guide

Server classifies setup problems (GitHub App not installed / wrong
installation / permissions / credentials, GHES base URL, repo target, no
projects, no agents, proxy token) as onboardingIssues[] on the status
payload, onboarding/guideStep on system alerts and deep-health checks.
The SPA appends a 'New hive? Open the 🧭 Guide → step …' link to every
surface rendering them, openWelcomeDialog(stepId) jumps to the step, the
Guide chip stays visible while any onboarding issue is active, and the
guide's GitHub App step prints the concrete GHES-aware install URL.

Closes #15772

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
…ml is generated)

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@clubanderson
clubanderson force-pushed the feat/onboarding-errors-open-guide branch from bced805 to 1c471a3 Compare October 30, 2026 19:15
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 30, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 080-awaiting-merge-admission → 050-review-pending: required-check-pending:coverage

@clubanderson
clubanderson merged commit 76a56df into v5 Oct 30, 2026
77 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/onboarding-errors-open-guide branch October 30, 2026 19:44
@github-actions

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

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

Labels

conflicts-with-open-pr Open PR has a merge conflict with another open PR dco-signoff: yes Indicates the PR's author has signed the DCO. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

dashboard: onboarding and GitHub App errors should point to the Getting Started guide

1 participant