diff --git a/changelog.d/added-onboarding-errors-open-guide.md b/changelog.d/added-onboarding-errors-open-guide.md new file mode 100644 index 0000000000..c765b581ac --- /dev/null +++ b/changelog.d/added-onboarding-errors-open-guide.md @@ -0,0 +1 @@ +- Onboarding problems the dashboard shows β€” GitHub App not installed / wrong installation / insufficient permissions / undelivered credentials, GHES base URL, project target, no projects, no agents β€” now carry a *New hive? Open the 🧭 Guide β†’ step …* link that opens the Getting Started guide at the matching step; the Guide chip stays visible while any such problem is active, the guide's GitHub App step prints the concrete install URL for the configured GitHub host, and `GET /api/status` exposes the classification as `onboardingIssues[]` (plus `onboarding`/`guideStep` on system alerts and deep-health checks) (#15772). diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index e5f6f6ea4b..153b03c268 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -24,6 +24,6 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1631` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1632` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1633` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1642` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1643` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1644` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index d9821e9a61..ffb9f714eb 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -63,4 +63,4 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:315` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:316` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:317` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1638` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1649` | diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index e3d6e648a6..4cd2182b36 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -8,17 +8,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` β€” the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` β€” one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` β€” `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` β€” the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)) | `pkg/dashboard/api.go:44` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` β€” the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:45` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:66` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1611` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1612` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1613` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1619` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` β€” the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N Β· $X this hour / today / this week / this month` figure (#15614) β€” the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` β€” issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures β€” the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store β€” distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired β€” details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer β€” the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`) | `pkg/dashboard/server.go:1624` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1625` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1626` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1627` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1628` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1629` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1630` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1622` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1623` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1624` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1630` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` β€” the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N Β· $X this hour / today / this week / this month` figure (#15614) β€” the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` β€” issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures β€” the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store β€” distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired β€” details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer β€” the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`) | `pkg/dashboard/server.go:1635` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1636` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1637` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1638` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1639` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1640` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1641` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | diff --git a/src/docs/api-reference/snapshots-and-style.md b/src/docs/api-reference/snapshots-and-style.md index b112c244ac..2f8063c389 100644 --- a/src/docs/api-reference/snapshots-and-style.md +++ b/src/docs/api-reference/snapshots-and-style.md @@ -6,7 +6,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| | `GET` | `/api/style` | Public | Sanitized custom dashboard CSS | `pkg/dashboard/api.go:46` | -| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1691` | +| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1702` | | `GET` | `/api/snapshot/frame-ancestors` | Public | Snapshot framing allowlist | `pkg/dashboard/api.go:79` | | `GET` | `/api/snapshot` | Public | Snapshot data | `pkg/dashboard/api.go:80` | | `GET` | `/snapshot` | Public | Public read-only snapshot page | `pkg/dashboard/api.go:81` | diff --git a/src/docs/getting-started.md b/src/docs/getting-started.md index f293599c6a..8c9fab08f5 100644 --- a/src/docs/getting-started.md +++ b/src/docs/getting-started.md @@ -57,7 +57,7 @@ below are the normal hosted path. The reclaim warning applies to hosted hives, not an unmanaged standalone deployment. 1. **Install the Forge App.** On the supported hosts, **GitHub.com and GitHub Enterprise (GHE), this is a GitHub App**. It lets Hive access the repositories you authorize. GitLab, Gitea, and Forgejo are **not supported for running a hive** today β€” see [Forge setup: GitLab, Gitea, and Forgejo](forge-app-setup.md). - - **From the dashboard (easiest):** click **Install Forge App** in the welcome checklist, or open **Governor Config β†’ Forge App** and use the install link there. Grant the app access to your repo. + - **From the dashboard (easiest):** click **Install Forge App** in the welcome checklist, or open **Governor Config β†’ Forge App** and use the install link there. Grant the app access to your repo. Can't find the checklist? It is the **🧭 Guide** button in the top navbar (also *Getting Started* in the sidebar); any GitHub App / setup error the dashboard shows carries an *Open the 🧭 Guide* link that jumps straight to this step, which also prints the install URL for your GitHub host. If you see neither the Guide nor the Governor Config gear, your account has the read-only role β€” ask the hive owner to grant access. - **On GitHub.com:** the install button sends you to `github.com/apps/` β€” pick your org/repo and approve. - **On GitHub Enterprise (IBM, corporate):** the same flow lives on your **GHE host**, not github.com β€” the install page is `https:///github-apps/`. Make sure your hive is pointed at your GHE host URL (Governor Config β†’ Forge App shows which host is configured). - **Self-hosting or creating the app yourself?** See the [GitHub App setup guide](github-app-setup.md) for app creation, permissions, and the `/gh-setup` flow. diff --git a/src/docs/operator-reference.md b/src/docs/operator-reference.md index 0492a60440..779199ce78 100644 --- a/src/docs/operator-reference.md +++ b/src/docs/operator-reference.md @@ -2077,6 +2077,29 @@ installation now and releases every item blocked on that permission when it is there. `GET /api/status` carries the same picture as `capabilities: {missing: ["workflows"], blocked_items: N, by_permission: {workflows: N}}`. +#### Onboarding errors point to the Getting Started guide + +Every setup problem the dashboard's **🧭 Guide** (top navbar; also *Getting +Started* in the sidebar) has a step for is classified server-side and rendered +with a tip β€” *New hive? Open the 🧭 Guide β†’ step β€˜Install the Forge App +(GitHub App)’ for the install URL and permissions checklist* β€” whose link opens +the guide at that step. The classification rides the status payload as +`onboardingIssues: [{kind, guideStep, message}]`, on system alerts as +`onboarding: true` + `guideStep`, and on the embedded `deepHealth` checks +(`github_auth`, `repo_target`) as `onboarding`/`guideStep`. Kinds: +`github-app-not-installed`, `github-app-wrong-installation`, +`github-app-permissions`, `github-app-credentials`, `github-base-url` +(β†’ step `github-app`), `repo-target`, `no-repos` (β†’ `repos`), `no-agents` +(β†’ `add-agent`), `proxy-token` (β†’ `welcome`). Error text is unchanged; the tip +is appended. While any onboarding issue is active the Guide chip stays visible +even if the checklist was dismissed earlier. The guide's GitHub App step shows +the concrete install URL for the configured forge host (`githubAppInstallURL`, +GHES-aware; on an enterprise host with no `github_app_slug` it says what to +configure instead of linking to github.com). The guide, its entry points and +the βš™οΈ Governor Config gear require a non-`read` role from `GET /api/role` β€” +a read-only viewer sees none of them and must be granted access via Manage +Access. + ## Runtime diagnostics (`debug`, `GOMEMLIMIT`, `mem:` log line) Added for [#14681](https://github.com/hivecommons/hive/issues/14681) (hive diff --git a/src/pkg/dashboard/onboarding.go b/src/pkg/dashboard/onboarding.go new file mode 100644 index 0000000000..5b3175da0f --- /dev/null +++ b/src/pkg/dashboard/onboarding.go @@ -0,0 +1,178 @@ +package dashboard + +import ( + "strings" + + "github.com/hivecommons/hive/pkg/config" +) + +// Onboarding problem kinds. Each one corresponds to a step of the dashboard's +// Getting Started guide (WELCOME_STEPS in static/index.html), so the SPA can +// append "open the 🧭 Guide β†’ step …" to whatever surface renders the error. +// Stable wire tokens β€” the SPA keys off them; rename only with the SPA. +const ( + OnboardingKindGitHubAppNotInstalled = "github-app-not-installed" + OnboardingKindGitHubAppWrongInstallation = "github-app-wrong-installation" + OnboardingKindGitHubAppPermissions = "github-app-permissions" + OnboardingKindGitHubAppCredentials = "github-app-credentials" + OnboardingKindGitHubBaseURL = "github-base-url" + OnboardingKindRepoTarget = "repo-target" + OnboardingKindNoRepos = "no-repos" + OnboardingKindNoAgents = "no-agents" + OnboardingKindProxyToken = "proxy-token" +) + +// Getting Started guide step ids (WELCOME_STEPS[*].id in static/index.html). +const ( + GuideStepGitHubApp = "github-app" + GuideStepRepos = "repos" + GuideStepAddAgent = "add-agent" + GuideStepWelcome = "welcome" +) + +// OnboardingIssue is one setup problem the Getting Started guide has a step +// for. It rides on the status payload (StatusPayload.OnboardingIssues) so +// every dashboard surface can render the same guide tip for it. +type OnboardingIssue struct { + Kind string `json:"kind"` + GuideStep string `json:"guideStep"` + Message string `json:"message,omitempty"` +} + +// onboardingKindGuideStep maps a kind to the guide step that fixes it. +func onboardingKindGuideStep(kind string) string { + switch kind { + case OnboardingKindGitHubAppNotInstalled, OnboardingKindGitHubAppWrongInstallation, + OnboardingKindGitHubAppPermissions, OnboardingKindGitHubAppCredentials, + OnboardingKindGitHubBaseURL: + return GuideStepGitHubApp + case OnboardingKindRepoTarget, OnboardingKindNoRepos: + return GuideStepRepos + case OnboardingKindNoAgents: + return GuideStepAddAgent + case OnboardingKindProxyToken: + return GuideStepWelcome + } + return "" +} + +// onboardingMessageRules is the ordered substring table behind +// ClassifyOnboardingMessage. First match wins, so the more specific +// phrasings (wrong installation, permissions) sit above the generic +// "installation"/"GitHub App" catch-alls. Matching is case-insensitive. +var onboardingMessageRules = []struct { + needle string + kind string +}{ + {"has no installation for", OnboardingKindGitHubAppNotInstalled}, + {"app not installed", OnboardingKindGitHubAppNotInstalled}, + {"app is not installed", OnboardingKindGitHubAppNotInstalled}, + {"installation_id is 0", OnboardingKindGitHubAppNotInstalled}, + {"installation id is 0", OnboardingKindGitHubAppNotInstalled}, + {"no installation id", OnboardingKindGitHubAppNotInstalled}, + {"installation not found", OnboardingKindGitHubAppWrongInstallation}, + {"installation id mismatch", OnboardingKindGitHubAppWrongInstallation}, + {"wrong installation", OnboardingKindGitHubAppWrongInstallation}, + {"installed on a different org", OnboardingKindGitHubAppWrongInstallation}, + {"different org", OnboardingKindGitHubAppWrongInstallation}, + {"pending org approval", OnboardingKindGitHubAppPermissions}, + {"insufficient permission", OnboardingKindGitHubAppPermissions}, + {"missing permission", OnboardingKindGitHubAppPermissions}, + {"permission issue", OnboardingKindGitHubAppPermissions}, + {"permissions: missing", OnboardingKindGitHubAppPermissions}, + {"resource not accessible by integration", OnboardingKindGitHubAppPermissions}, + {"private key", OnboardingKindGitHubAppCredentials}, + {"credentials not delivered", OnboardingKindGitHubAppCredentials}, + {"never assigned a github app", OnboardingKindGitHubAppCredentials}, + {"placeholder github.app_id", OnboardingKindGitHubAppCredentials}, + {"github.app_id", OnboardingKindGitHubAppCredentials}, + {"github app id", OnboardingKindGitHubAppCredentials}, + {"github.base_url", OnboardingKindGitHubBaseURL}, + {"github base_url", OnboardingKindGitHubBaseURL}, + {"github base url", OnboardingKindGitHubBaseURL}, + {"github_app_slug", OnboardingKindGitHubBaseURL}, + {"proxy token", OnboardingKindProxyToken}, + {"proxy_token", OnboardingKindProxyToken}, + {"no repos configured", OnboardingKindNoRepos}, + {"no repositories configured", OnboardingKindNoRepos}, + {"no projects configured", OnboardingKindNoRepos}, + {"target misconfigured", OnboardingKindRepoTarget}, + {"expected owner/name", OnboardingKindRepoTarget}, + {"expected org/repo", OnboardingKindRepoTarget}, + {"primary_repo", OnboardingKindRepoTarget}, + {"no agents configured", OnboardingKindNoAgents}, + {"no agents defined", OnboardingKindNoAgents}, + // Generic GitHub App catch-all last: any remaining App-shaped message is + // still a "Connect the GitHub App" problem for a new hive. + {"github app", OnboardingKindGitHubAppNotInstalled}, +} + +// ClassifyOnboardingMessage maps a human-readable error/alert message to an +// onboarding kind and the Getting Started guide step that fixes it. ok is +// false for messages that are not setup problems (budget, CI, agent crashes). +// The message text itself is never altered β€” callers keep rendering it. +func ClassifyOnboardingMessage(msg string) (kind, guideStep string, ok bool) { + m := strings.ToLower(strings.TrimSpace(msg)) + if m == "" { + return "", "", false + } + for _, r := range onboardingMessageRules { + if strings.Contains(m, r.needle) { + return r.kind, onboardingKindGuideStep(r.kind), true + } + } + return "", "", false +} + +// onboardingKindForGitHubAppState maps a pkg/github AppAuthState wire token to +// the onboarding kind. Unknown/empty tokens yield "". +func onboardingKindForGitHubAppState(state string) string { + switch state { + case githubAppStateNotInstalledToken: + return OnboardingKindGitHubAppNotInstalled + case "wrong-installation": + return OnboardingKindGitHubAppWrongInstallation + case githubAppStateKeyMissingToken, githubAppStateKeyInvalidToken, githubAppStateNoAppAssignedToken: + return OnboardingKindGitHubAppCredentials + } + return "" +} + +// onboardingIssuesFor derives the onboarding problems in force from a status +// payload (after its GitHub App / repo-target fields are final) plus config. +// Pure: no locks, no I/O. Order is the guide's own order (GitHub App first). +func onboardingIssuesFor(status *StatusPayload, cfg *config.Config) []OnboardingIssue { + if status == nil { + return nil + } + var out []OnboardingIssue + add := func(kind, msg string) { + out = append(out, OnboardingIssue{Kind: kind, GuideStep: onboardingKindGuideStep(kind), Message: msg}) + } + + if status.GitHubAppRequired || status.GitHubAppInstallMissing { + kind := onboardingKindForGitHubAppState(status.GitHubAppState) + if kind == "" { + if k, _, ok := ClassifyOnboardingMessage(status.GitHubAppPermIssue); ok && strings.HasPrefix(k, "github-app-") { + kind = k + } else if status.GitHubAppPermIssue != "" { + kind = OnboardingKindGitHubAppPermissions + } else { + kind = OnboardingKindGitHubAppNotInstalled + } + } + add(kind, status.GitHubAppPermIssue) + } + if status.RepoTargetMisconfigured { + add(OnboardingKindRepoTarget, status.RepoTargetIssue) + } + if cfg != nil { + if len(cfg.Project.Repos) == 0 && strings.TrimSpace(cfg.Project.PrimaryRepo) == "" { + add(OnboardingKindNoRepos, "No projects configured β€” add at least one project and mark the primary") + } + } + if cfg != nil && len(status.Agents) == 0 { + add(OnboardingKindNoAgents, "No agents configured β€” add an agent so the hive can work") + } + return out +} diff --git a/src/pkg/dashboard/onboarding_test.go b/src/pkg/dashboard/onboarding_test.go new file mode 100644 index 0000000000..402090156a --- /dev/null +++ b/src/pkg/dashboard/onboarding_test.go @@ -0,0 +1,227 @@ +package dashboard + +import ( + "encoding/json" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" +) + +// The dashboard must say "open the 🧭 Guide" itself whenever it shows an +// onboarding problem: a new GHE operator read "GitHub App 5686 has no +// installation for this org" and had to ask Slack for the install URL and +// where the guide was. These tests pin the server-side classification the +// SPA keys off (kind + guide step) and its presence on the status payload. + +func TestClassifyOnboardingMessage(t *testing.T) { + cases := []struct { + msg string + wantKind string + wantStep string + wantOK bool + }{ + {"GitHub App permission issue: GitHub App 5686 has no installation for this org β€” install it (the spoke adopts the installation automatically)", OnboardingKindGitHubAppNotInstalled, GuideStepGitHubApp, true}, + {"GitHub App not installed β€” no installation for this org", OnboardingKindGitHubAppNotInstalled, GuideStepGitHubApp, true}, + {"GitHub App install pending β€” the App is not yet installed on the org", OnboardingKindGitHubAppNotInstalled, GuideStepGitHubApp, true}, + {"installation_id points at a different org than project.org", OnboardingKindGitHubAppWrongInstallation, GuideStepGitHubApp, true}, + {"GitHub App is installed but pending org approval", OnboardingKindGitHubAppPermissions, GuideStepGitHubApp, true}, + {"GitHub App permissions: missing `workflows` Β· 3 items blocked", OnboardingKindGitHubAppPermissions, GuideStepGitHubApp, true}, + {"Resource not accessible by integration", OnboardingKindGitHubAppPermissions, GuideStepGitHubApp, true}, + {"GitHub App credentials not delivered by the hub β€” agents cannot act as the App (operator action; no action needed from the hive owner)", OnboardingKindGitHubAppCredentials, GuideStepGitHubApp, true}, + {"GitHub App private key does not match the App it authenticates as β€” GitHub rejects its JWT (operator must push the correct key)", OnboardingKindGitHubAppCredentials, GuideStepGitHubApp, true}, + {"This hive still carries the placeholder github.app_id", OnboardingKindGitHubAppCredentials, GuideStepGitHubApp, true}, + {"github.base_url is not a valid URL for this enterprise host", OnboardingKindGitHubBaseURL, GuideStepGitHubApp, true}, + {"Project target misconfigured β€” expected owner/name. Fix in Settings β†’ Projects.", OnboardingKindRepoTarget, GuideStepRepos, true}, + {"primary_repo \"hive\" is not one of project.repos", OnboardingKindRepoTarget, GuideStepRepos, true}, + {"No projects configured β€” add at least one project", OnboardingKindNoRepos, GuideStepRepos, true}, + {"No agents configured β€” add an agent", OnboardingKindNoAgents, GuideStepAddAgent, true}, + {"hub proxy token missing β€” dashboard links will not authenticate", OnboardingKindProxyToken, GuideStepWelcome, true}, + // Not onboarding: must stay untouched so budget/CI/crash alerts never + // grow a misleading "open the guide" tip. + {"Weekly token budget 95% consumed", "", "", false}, + {"agent scanner restarted 4 times in 10 minutes", "", "", false}, + {"CI failing on main for 3 hours", "", "", false}, + {"tmux not installed on this host", "", "", false}, + {"", "", "", false}, + } + for _, tc := range cases { + kind, step, ok := ClassifyOnboardingMessage(tc.msg) + if ok != tc.wantOK || kind != tc.wantKind || step != tc.wantStep { + t.Errorf("ClassifyOnboardingMessage(%q) = (%q, %q, %v), want (%q, %q, %v)", tc.msg, kind, step, ok, tc.wantKind, tc.wantStep, tc.wantOK) + } + } +} + +func TestOnboardingKindGuideStep_EveryKindHasAStep(t *testing.T) { + for _, kind := range []string{ + OnboardingKindGitHubAppNotInstalled, OnboardingKindGitHubAppWrongInstallation, + OnboardingKindGitHubAppPermissions, OnboardingKindGitHubAppCredentials, + OnboardingKindGitHubBaseURL, OnboardingKindRepoTarget, OnboardingKindNoRepos, + OnboardingKindNoAgents, OnboardingKindProxyToken, + } { + if onboardingKindGuideStep(kind) == "" { + t.Errorf("kind %q has no guide step β€” the SPA tip would point nowhere", kind) + } + } + if got := onboardingKindGuideStep("budget-exceeded"); got != "" { + t.Errorf("unknown kind mapped to step %q, want none", got) + } +} + +func TestOnboardingIssuesFor_GitHubAppStates(t *testing.T) { + cases := []struct { + name string + status StatusPayload + want string + }{ + {"not installed (config truth)", StatusPayload{GitHubAppInstallMissing: true, GitHubAppRequired: true, GitHubAppState: "not-installed"}, OnboardingKindGitHubAppNotInstalled}, + {"wrong installation", StatusPayload{GitHubAppRequired: true, GitHubAppState: "wrong-installation"}, OnboardingKindGitHubAppWrongInstallation}, + {"key missing", StatusPayload{GitHubAppRequired: true, GitHubAppState: "key-missing"}, OnboardingKindGitHubAppCredentials}, + {"key invalid", StatusPayload{GitHubAppRequired: true, GitHubAppState: "key-invalid"}, OnboardingKindGitHubAppCredentials}, + {"no app assigned", StatusPayload{GitHubAppRequired: true, GitHubAppState: "no-app-assigned"}, OnboardingKindGitHubAppCredentials}, + {"perm issue, unclassified state", StatusPayload{GitHubAppRequired: true, GitHubAppPermIssue: "GitHub App is installed but pending org approval"}, OnboardingKindGitHubAppPermissions}, + {"required with no detail", StatusPayload{GitHubAppRequired: true}, OnboardingKindGitHubAppNotInstalled}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + st := tc.status + st.Agents = []FrontendAgent{{Name: "scanner"}} + got := onboardingIssuesFor(&st, nil) + if len(got) != 1 { + t.Fatalf("got %d issues, want 1: %+v", len(got), got) + } + if got[0].Kind != tc.want || got[0].GuideStep != GuideStepGitHubApp { + t.Errorf("issue = %+v, want kind %q step %q", got[0], tc.want, GuideStepGitHubApp) + } + if got[0].Message != tc.status.GitHubAppPermIssue { + t.Errorf("message %q altered; the server must keep the diagnostic text verbatim", got[0].Message) + } + }) + } +} + +func TestOnboardingIssuesFor_NothingWhenHealthy(t *testing.T) { + cfg := &config.Config{} + cfg.Project.Org = "hivecommons" + cfg.Project.Repos = []string{"hive"} + cfg.Project.PrimaryRepo = "hive" + st := &StatusPayload{Agents: []FrontendAgent{{Name: "scanner"}}} + if got := onboardingIssuesFor(st, cfg); len(got) != 0 { + t.Errorf("healthy hive produced onboarding issues: %+v", got) + } + if got := onboardingIssuesFor(nil, cfg); got != nil { + t.Errorf("nil status produced %+v", got) + } +} + +func TestOnboardingIssuesFor_RepoTargetNoReposNoAgents(t *testing.T) { + cfg := &config.Config{} + st := &StatusPayload{RepoTargetMisconfigured: true, RepoTargetIssue: "primary_repo must be org/repo"} + got := onboardingIssuesFor(st, cfg) + kinds := map[string]string{} + for _, i := range got { + kinds[i.Kind] = i.GuideStep + } + if kinds[OnboardingKindRepoTarget] != GuideStepRepos { + t.Errorf("repo-target β†’ step %q, want %q (issues: %+v)", kinds[OnboardingKindRepoTarget], GuideStepRepos, got) + } + if kinds[OnboardingKindNoRepos] != GuideStepRepos { + t.Errorf("no-repos β†’ step %q, want %q", kinds[OnboardingKindNoRepos], GuideStepRepos) + } + if kinds[OnboardingKindNoAgents] != GuideStepAddAgent { + t.Errorf("no-agents β†’ step %q, want %q", kinds[OnboardingKindNoAgents], GuideStepAddAgent) + } +} + +// The status payload (and therefore every SSE tick) must carry the +// classification for the exact GHE case from the report: real App ID, +// installation_id 0 β€” so the banner tip, the health pill, and the Guide chip +// all key off the same server truth. +func TestUpdateStatus_OnboardingIssuesOnPayload(t *testing.T) { + s := newFullServer(t) + s.deps.Config.GitHub = gheAppPostResetConfig() + + status := &StatusPayload{Agents: []FrontendAgent{{Name: "scanner"}}} + s.UpdateStatus(status) + + var ghApp *OnboardingIssue + for i := range status.OnboardingIssues { + if status.OnboardingIssues[i].GuideStep == GuideStepGitHubApp { + ghApp = &status.OnboardingIssues[i] + } + } + if ghApp == nil { + t.Fatalf("OnboardingIssues = %+v, want a github-app step entry for installation_id 0", status.OnboardingIssues) + } + if ghApp.Kind != OnboardingKindGitHubAppNotInstalled { + t.Errorf("kind = %q, want %q", ghApp.Kind, OnboardingKindGitHubAppNotInstalled) + } + + raw, err := json.Marshal(status) + if err != nil { + t.Fatal(err) + } + for _, want := range []string{`"onboardingIssues":[`, `"kind":"github-app-not-installed"`, `"guideStep":"github-app"`} { + if !strings.Contains(string(raw), want) { + t.Errorf("status JSON missing %s", want) + } + } + + // The embedded deep-health check carries the same marker so the header + // pill tooltip can append the guide pointer. + s.SetGitHubAppRequired(true) + s.SetGitHubAppState("not-installed") + health := s.healthSummaryFor(status, true) + hraw, _ := json.Marshal(health) + if !strings.Contains(string(hraw), `"name":"github_auth"`) || !strings.Contains(string(hraw), `"onboarding":true`) || !strings.Contains(string(hraw), `"guideStep":"github-app"`) { + t.Errorf("deep health github_auth check lacks onboarding/guideStep: %s", hraw) + } +} + +func TestUpdateStatus_NoOnboardingIssuesWhenInstalled(t *testing.T) { + s := newFullServer(t) + g := gheAppPostResetConfig() + g.InstallationID = 12345678 + s.deps.Config.GitHub = g + s.deps.Config.Project.Org = "hivecommons" + s.deps.Config.Project.Repos = []string{"hive"} + s.deps.Config.Project.PrimaryRepo = "hive" + + status := &StatusPayload{Agents: []FrontendAgent{{Name: "scanner"}}} + s.UpdateStatus(status) + for _, i := range status.OnboardingIssues { + if strings.HasPrefix(i.Kind, "github-app-") { + t.Errorf("installed App still classified as %+v", i) + } + } +} + +func TestAddSystemAlert_ClassifiesOnboarding(t *testing.T) { + s := newTestServer() + s.AddSystemAlert("gh-app", "error", "GitHub App permission issue: GitHub App 5686 has no installation for this org β€” install it") + s.AddSystemAlert("budget", "warning", "Weekly token budget 95% consumed") + + s.systemAlertsMu.Lock() + alerts := append([]SystemAlert(nil), s.systemAlerts...) + s.systemAlertsMu.Unlock() + byID := map[string]SystemAlert{} + for _, a := range alerts { + byID[a.ID] = a + } + if a := byID["gh-app"]; !a.Onboarding || a.GuideStep != GuideStepGitHubApp { + t.Errorf("gh-app alert = %+v, want onboarding=true guideStep=%q", a, GuideStepGitHubApp) + } + if a := byID["budget"]; a.Onboarding || a.GuideStep != "" { + t.Errorf("budget alert = %+v, must not be classified as onboarding", a) + } + // Updating an existing alert re-classifies it from the new message. + s.AddSystemAlert("gh-app", "info", "all good now") + s.systemAlertsMu.Lock() + defer s.systemAlertsMu.Unlock() + for _, a := range s.systemAlerts { + if a.ID == "gh-app" && (a.Onboarding || a.GuideStep != "") { + t.Errorf("updated alert kept stale onboarding marker: %+v", a) + } + } +} diff --git a/src/pkg/dashboard/server.go b/src/pkg/dashboard/server.go index c9b45643e9..2b40cb4faf 100644 --- a/src/pkg/dashboard/server.go +++ b/src/pkg/dashboard/server.go @@ -670,9 +670,15 @@ type StatusPayload struct { // banner; omitted when every watched repo accepts issues. IssuesDisabledRepos []IssuesDisabledRepo `json:"issuesDisabledRepos,omitempty"` GitHubBaseURL string `json:"githubBaseURL,omitempty"` - InferenceBackends []InferenceBackend `json:"inferenceBackends,omitempty"` - SystemAlerts []SystemAlert `json:"systemAlerts,omitempty"` - HubBanner *HubBannerState `json:"hubBanner,omitempty"` + // OnboardingIssues lists the setup problems in force that the Getting + // Started guide has a step for (GitHub App not installed / wrong org / + // permissions / credentials, repo target, no projects, no agents). The + // SPA appends an "open the 🧭 Guide β†’ step …" tip wherever these are + // rendered and keeps the Guide chip visible while any is active. + OnboardingIssues []OnboardingIssue `json:"onboardingIssues,omitempty"` + InferenceBackends []InferenceBackend `json:"inferenceBackends,omitempty"` + SystemAlerts []SystemAlert `json:"systemAlerts,omitempty"` + HubBanner *HubBannerState `json:"hubBanner,omitempty"` // Platform surfaces the v4 spoke capabilities β€” the configured forge, the // mint token service state, and the skills registry. It is additive and // nil-safe: a github-only, mint-off hive with no skills dir still gets a @@ -784,6 +790,11 @@ type SystemAlert struct { ID string `json:"id"` Severity string `json:"severity"` Message string `json:"message"` + // Onboarding/GuideStep are set (ClassifyOnboardingMessage) when the + // message is a setup problem the Getting Started guide has a step for, + // so the alert row can offer "open the 🧭 Guide β†’ step …". + Onboarding bool `json:"onboarding,omitempty"` + GuideStep string `json:"guideStep,omitempty"` } // InferenceBackend describes a live inference endpoint and its available models. @@ -2687,6 +2698,13 @@ func (s *Server) UpdateStatusIfFresh(status *StatusPayload, buildEpoch uint64) b status.GitHubAppInstallURL = g.AppInstallURL() } } + // Derived AFTER the GitHub App / repo-target fields are final so the + // classification never disagrees with the banners rendered from them. + var onboardingCfg *config.Config + if s.deps != nil { + onboardingCfg = s.deps.Config + } + status.OnboardingIssues = onboardingIssuesFor(status, onboardingCfg) status.InferenceBackends = s.buildInferenceBackends() if runs, err := s.activeRuns(false); err == nil { @@ -2801,14 +2819,17 @@ func (s *Server) UpdateStatusIfFresh(status *StatusPayload, buildEpoch uint64) b func (s *Server) AddSystemAlert(id, severity, message string) { s.systemAlertsMu.Lock() defer s.systemAlertsMu.Unlock() + _, guideStep, onboarding := ClassifyOnboardingMessage(message) for i, a := range s.systemAlerts { if a.ID == id { s.systemAlerts[i].Message = message s.systemAlerts[i].Severity = severity + s.systemAlerts[i].Onboarding = onboarding + s.systemAlerts[i].GuideStep = guideStep return } } - s.systemAlerts = append(s.systemAlerts, SystemAlert{ID: id, Severity: severity, Message: message}) + s.systemAlerts = append(s.systemAlerts, SystemAlert{ID: id, Severity: severity, Message: message, Onboarding: onboarding, GuideStep: guideStep}) } // ClearSystemAlert removes an alert by ID. @@ -3345,11 +3366,11 @@ func (s *Server) handleHealthDeep(w http.ResponseWriter, r *http.Request) { // 2. GitHub auth β€” config truth first (see githubAppNotInstalled and // githubAppCredsUndelivered). if s.githubAppNotInstalled() { - checks["github_auth"] = map[string]any{"status": "fail", "detail": "GitHub App not installed β€” no installation for this org"} + checks["github_auth"] = map[string]any{"status": "fail", "detail": "GitHub App not installed β€” no installation for this org", "onboarding": true, "guideStep": GuideStepGitHubApp} overall = "degraded" failCount++ } else if detail := s.githubAppCredsUndelivered(); detail != "" { - checks["github_auth"] = map[string]any{"status": "fail", "detail": detail} + checks["github_auth"] = map[string]any{"status": "fail", "detail": detail, "onboarding": true, "guideStep": GuideStepGitHubApp} overall = "degraded" failCount++ } else if s.deps != nil && s.deps.GHAppAuth != nil { @@ -4654,6 +4675,10 @@ func (s *Server) healthSummaryFor(status *StatusPayload, ready bool) map[string] Name string `json:"name"` Status string `json:"status"` Detail string `json:"detail,omitempty"` + // Onboarding/GuideStep mark setup problems the Getting Started guide + // has a step for (see OnboardingIssue); the SPA renders a guide tip. + Onboarding bool `json:"onboarding,omitempty"` + GuideStep string `json:"guideStep,omitempty"` } checks := []check{} fails := 0 @@ -4670,10 +4695,10 @@ func (s *Server) healthSummaryFor(status *StatusPayload, ready bool) map[string] // 2. GitHub auth β€” config truth first (see githubAppNotInstalled and // githubAppCredsUndelivered). if s.githubAppNotInstalled() { - checks = append(checks, check{Name: "github_auth", Status: "fail", Detail: "GitHub App not installed β€” no installation for this org"}) + checks = append(checks, check{Name: "github_auth", Status: "fail", Detail: "GitHub App not installed β€” no installation for this org", Onboarding: true, GuideStep: GuideStepGitHubApp}) fails++ } else if detail := s.githubAppCredsUndelivered(); detail != "" { - checks = append(checks, check{Name: "github_auth", Status: "fail", Detail: detail}) + checks = append(checks, check{Name: "github_auth", Status: "fail", Detail: detail, Onboarding: true, GuideStep: GuideStepGitHubApp}) fails++ } else if s.deps != nil && s.deps.GHAppAuth != nil { if _, err := s.deps.GHAppAuth.Token(s.deps.Ctx); err != nil { @@ -4701,7 +4726,7 @@ func (s *Server) healthSummaryFor(status *StatusPayload, ready bool) map[string] } if status != nil && status.RepoTargetMisconfigured { - checks = append(checks, check{Name: "repo_target", Status: "warn", Detail: status.RepoTargetIssue}) + checks = append(checks, check{Name: "repo_target", Status: "warn", Detail: status.RepoTargetIssue, Onboarding: true, GuideStep: GuideStepRepos}) warns++ } diff --git a/src/pkg/dashboard/static-src/css/auth.css b/src/pkg/dashboard/static-src/css/auth.css index 903c4e0857..4c5d47f7f2 100644 --- a/src/pkg/dashboard/static-src/css/auth.css +++ b/src/pkg/dashboard/static-src/css/auth.css @@ -141,6 +141,14 @@ .gh-app-perm-details { font-size: 0.8rem; margin-top: var(--sp-3); color: var(--text); } .gh-app-perm-details .perm-ok { color: var(--green); } .gh-app-perm-details .perm-missing { color: var(--red); font-weight: 600; } + /* Onboarding guide tip β€” appended under any onboarding-kind problem + (GitHub App, repo target, system alert) so a new operator is pointed at + the 🧭 Guide instead of asking Slack for the install URL. */ + .onboarding-guide-tip { font-size: var(--fs-sm); color: var(--muted); margin-top: var(--sp-3); } + .onboarding-guide-tip .onboarding-guide-link { color: var(--accent); font-weight: 600; cursor: pointer; text-decoration: underline; } + .onboarding-guide-tip .onboarding-guide-link:hover, .onboarding-guide-tip .onboarding-guide-link:focus-visible { text-decoration: none; } + .welcome-install-url { margin-top: var(--sp-3); font-size: var(--fs-sm); word-break: break-all; } + .welcome-install-url code { color: var(--text); } /* .gh-auth-overlay/.gh-auth-modal β€” modal overlay/panel recipes (end of style block). z-index encodes stacking intent β€” do not change. */ .gh-auth-overlay { z-index: 9999; } diff --git a/src/pkg/dashboard/static-src/html/root-notices.html b/src/pkg/dashboard/static-src/html/root-notices.html index acbbb8df6a..412a495aeb 100644 --- a/src/pkg/dashboard/static-src/html/root-notices.html +++ b/src/pkg/dashboard/static-src/html/root-notices.html @@ -9,6 +9,7 @@
GitHub App Not Installed
This hive cannot create issues or advisory reports. Install the Hive Hub GitHub App on your project; this hive checks every few minutes and will configure itself, or you can paste the Installation ID below.
+