[server, dashboard, db] Org-wide "maintenance mode" (#20813)

* [dashboard] Initial infra rollout page, incl. list running workspaces

* [server, db, dashboard] Allow org-owner to stop workspace on all workspaces in the organization

Also, fix maintenanceMode update

* [public-api, db, server, dashboard] Introduce MaintenanceNofitication banner that can be configured per org

* review comments: use mutation instead of callback for state mutation

* Fix workspace start prevention

* Review comments around banners and rendering

 - permissions issues
 - add banner to /new page
 - a bunch of rendering issues and alignments
 - renaming some things for clarity (dropped "Scheduled" prefixes)
 - only allow up to 255 characters in notification messages

* [dashboard] Only show Admin entry for dedicated

* [server] Fix permissions for setMaintenanceMode to "maintenance"

* [dashboard] Adjusted copy incl. default notification message

* Review coments: re-use and fix styles, and naming

Co-authored-by: Filip Troníček <[email protected]>

* Minor copy improvements

* [server] Fix bogus permission check in stopWorkspace

---------

Co-authored-by: Filip Troníček <[email protected]>

Author: geropl

components/dashboard/src/AppNotifications.tsx

@@ -18,6 +18,8 @@ import { AttributionId } from "@gitpod/gitpod-protocol/lib/attribution";
 import { getGitpodService } from "./service/service";
 import { useOrgBillingMode } from "./data/billing-mode/org-billing-mode-query";
 import { Organization } from "@gitpod/public-api/lib/gitpod/v1/organization_pb";
+import { MaintenanceModeBanner } from "./org-admin/MaintenanceModeBanner";
+import { MaintenanceNotificationBanner } from "./org-admin/MaintenanceNotificationBanner";
 
 const KEY_APP_DISMISSED_NOTIFICATIONS = "gitpod-app-notifications-dismissed";
 const PRIVACY_POLICY_LAST_UPDATED = "2024-12-03";
@@ -208,29 +210,29 @@ export function AppNotifications() {
         setTopNotification(undefined);
     }, [topNotification, setTopNotification]);
 
-    if (!topNotification) {
-        return <></>;
-    }
-
     return (
         <div className="app-container pt-2">
-            <Alert
-                type={topNotification.type}
-                closable={topNotification.id !== "gitpod-classic-sunset"} // Only show close button if it's not the sunset notification
-                onClose={() => {
-                    if (!topNotification.preventDismiss) {
-                        dismissNotification();
-                    } else {
-                        if (topNotification.onClose) {
-                            topNotification.onClose();
+            <MaintenanceModeBanner />
+            <MaintenanceNotificationBanner />
+            {topNotification && (
+                <Alert
+                    type={topNotification.type}
+                    closable={topNotification.id !== "gitpod-classic-sunset"} // Only show close button if it's not the sunset notification
+                    onClose={() => {
+                        if (!topNotification.preventDismiss) {
+                            dismissNotification();
+                        } else {
+                            if (topNotification.onClose) {
+                                topNotification.onClose();
+                            }
                         }
-                    }
-                }}
-                showIcon={true}
-                className="flex rounded mb-2 w-full"
-            >
-                <span>{topNotification.message}</span>
-            </Alert>
+                    }}
+                    showIcon={true}
+                    className="flex rounded mb-2 w-full"
+                >
+                    <span>{topNotification.message}</span>
+                </Alert>
+            )}
         </div>
     );
 }

components/dashboard/src/app/AppRoutes.tsx

@@ -79,6 +79,7 @@ const ConfigurationDetailPage = React.lazy(
 );
 
 const PrebuildListPage = React.lazy(() => import(/* webpackPrefetch: true */ "../prebuilds/list/PrebuildListPage"));
+const AdminPage = React.lazy(() => import(/* webpackPrefetch: true */ "../org-admin/AdminPage"));
 
 export const AppRoutes = () => {
     const hash = getURLHash();
@@ -205,6 +206,7 @@ export const AppRoutes = () => {
                             {/* TODO: migrate other org settings pages underneath /settings prefix so we can utilize nested routes */}
                             <Route exact path="/billing" component={TeamUsageBasedBilling} />
                             <Route exact path="/sso" component={SSO} />
+                            <Route exact path="/org-admin" component={AdminPage} />
 
                             <Route exact path={`/prebuilds`} component={PrebuildListPage} />
                             <Route path="/prebuilds/:prebuildId" component={PrebuildDetailPage} />

components/dashboard/src/data/maintenance-mode/maintenance-mode-mutation.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCurrentOrg } from "../organizations/orgs-query";
+import { organizationClient } from "../../service/public-api";
+import { maintenanceModeQueryKey } from "./maintenance-mode-query";
+
+export interface SetMaintenanceModeArgs {
+    enabled: boolean;
+}
+
+export const useSetMaintenanceModeMutation = () => {
+    const { data: org } = useCurrentOrg();
+    const queryClient = useQueryClient();
+    const organizationId = org?.id ?? "";
+
+    return useMutation<boolean, Error, SetMaintenanceModeArgs>({
+        mutationFn: async ({ enabled }) => {
+            if (!organizationId) {
+                throw new Error("No organization selected");
+            }
+
+            try {
+                const response = await organizationClient.setOrganizationMaintenanceMode({
+                    organizationId,
+                    enabled,
+                });
+                return response.enabled;
+            } catch (error) {
+                console.error("Failed to set maintenance mode", error);
+                throw error;
+            }
+        },
+        onSuccess: (result) => {
+            // Update the cache
+            queryClient.setQueryData(maintenanceModeQueryKey(organizationId), result);
+        },
+    });
+};

components/dashboard/src/data/maintenance-mode/maintenance-mode-query.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { useCurrentOrg } from "../organizations/orgs-query";
+import { organizationClient } from "../../service/public-api";
+
+export const maintenanceModeQueryKey = (orgId: string) => ["maintenance-mode", orgId];
+
+export const useMaintenanceMode = () => {
+    const { data: org } = useCurrentOrg();
+
+    const { data: isMaintenanceMode = false, isLoading } = useQuery(
+        maintenanceModeQueryKey(org?.id || ""),
+        async () => {
+            if (!org?.id) return false;
+
+            try {
+                const response = await organizationClient.getOrganizationMaintenanceMode({
+                    organizationId: org.id,
+                });
+                return response.enabled;
+            } catch (error) {
+                console.error("Failed to fetch maintenance mode status", error);
+                return false;
+            }
+        },
+        {
+            enabled: !!org?.id,
+            staleTime: 30 * 1000, // 30 seconds
+            refetchInterval: 60 * 1000, // 1 minute
+        },
+    );
+
+    return {
+        isMaintenanceMode,
+        isLoading,
+    };
+};

components/dashboard/src/data/maintenance-mode/maintenance-notification-mutation.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCurrentOrg } from "../organizations/orgs-query";
+import { organizationClient } from "../../service/public-api";
+import { MaintenanceNotification } from "@gitpod/gitpod-protocol";
+import { maintenanceNotificationQueryKey } from "./maintenance-notification-query";
+
+export interface SetMaintenanceNotificationArgs {
+    isEnabled: boolean;
+    customMessage?: string;
+}
+
+export const useSetMaintenanceNotificationMutation = () => {
+    const { data: org } = useCurrentOrg();
+    const queryClient = useQueryClient();
+    const organizationId = org?.id ?? "";
+
+    return useMutation<MaintenanceNotification, Error, SetMaintenanceNotificationArgs>({
+        mutationFn: async ({ isEnabled, customMessage }) => {
+            if (!organizationId) {
+                throw new Error("No organization selected");
+            }
+
+            try {
+                const response = await organizationClient.setMaintenanceNotification({
+                    organizationId,
+                    isEnabled,
+                    customMessage,
+                });
+
+                const result: MaintenanceNotification = {
+                    enabled: response.isEnabled,
+                    message: response.message,
+                };
+
+                return result;
+            } catch (error) {
+                console.error("Failed to set maintenance notification", error);
+                throw error;
+            }
+        },
+        onSuccess: (result) => {
+            // Update the cache
+            queryClient.setQueryData(maintenanceNotificationQueryKey(organizationId), result);
+        },
+    });
+};

components/dashboard/src/data/maintenance-mode/maintenance-notification-query.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { useCurrentOrg } from "../organizations/orgs-query";
+import { organizationClient } from "../../service/public-api";
+import { MaintenanceNotification } from "@gitpod/gitpod-protocol";
+
+export const maintenanceNotificationQueryKey = (orgId: string) => ["maintenance-notification", orgId];
+
+export const useMaintenanceNotification = () => {
+    const { data: org } = useCurrentOrg();
+
+    const { data, isLoading } = useQuery<MaintenanceNotification>(
+        maintenanceNotificationQueryKey(org?.id || ""),
+        async () => {
+            if (!org?.id) return { enabled: false };
+
+            try {
+                const response = await organizationClient.getMaintenanceNotification({
+                    organizationId: org.id,
+                });
+                return {
+                    enabled: response.isEnabled,
+                    message: response.message,
+                };
+            } catch (error) {
+                console.error("Failed to fetch maintenance notification settings", error);
+                return { enabled: false };
+            }
+        },
+        {
+            enabled: !!org?.id,
+            staleTime: 30 * 1000, // 30 seconds
+            refetchInterval: 60 * 1000, // 1 minute
+        },
+    );
+
+    return {
+        isNotificationEnabled: data?.enabled || false,
+        notificationMessage: data?.message,
+        isLoading,
+    };
+};

components/dashboard/src/menu/OrganizationSelector.tsx

@@ -127,6 +127,17 @@ export default function OrganizationSelector() {
                 separator: false,
                 link: "/settings",
             });
+
+            if (isOwner && isDedicated) {
+                // Add Admin link for owners
+                linkEntries.push({
+                    title: "Organization Administration",
+                    customContent: <LinkEntry>Organization Administration</LinkEntry>,
+                    active: false,
+                    separator: false,
+                    link: "/org-admin",
+                });
+            }
         }
     }
 

components/dashboard/src/org-admin/AdminPage.tsx

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import React, { useEffect } from "react";
+import { useHistory } from "react-router-dom";
+import { useUserLoader } from "../hooks/use-user-loader";
+import { useCurrentOrg } from "../data/organizations/orgs-query";
+import { useIsOwner } from "../data/organizations/members-query";
+import Header from "../components/Header";
+import { SpinnerLoader } from "../components/Loader";
+import { RunningWorkspacesCard } from "./RunningWorkspacesCard";
+import { MaintenanceModeCard } from "./MaintenanceModeCard";
+import { MaintenanceNotificationCard } from "./MaintenanceNotificationCard";
+import { Heading2 } from "@podkit/typography/Headings";
+
+const AdminPage: React.FC = () => {
+    const history = useHistory();
+    const { loading: userLoading } = useUserLoader();
+    const { data: currentOrg, isLoading: orgLoading } = useCurrentOrg();
+    const isOwner = useIsOwner();
+
+    useEffect(() => {
+        if (userLoading || orgLoading) {
+            return;
+        }
+        if (!isOwner) {
+            history.replace("/workspaces");
+        }
+    }, [isOwner, userLoading, orgLoading, history, currentOrg?.id]);
+
+    return (
+        <div className="flex flex-col w-full">
+            <Header title="Organization Administration" subtitle="Manage Infrastructure Rollouts" />
+            <div className="app-container py-6 flex flex-col gap-4">
+                <Heading2>Infrastructure Rollout</Heading2>
+
+                {userLoading ||
+                    orgLoading ||
+                    (!isOwner && (
+                        <div className="flex items-center justify-center w-full p-8">
+                            <SpinnerLoader />
+                        </div>
+                    ))}
+
+                {!orgLoading && !currentOrg && (
+                    <div className="text-red-500 p-4 bg-red-100 dark:bg-red-900 border border-red-500 rounded-md">
+                        Could not load organization details. Please ensure you are part of an organization.
+                    </div>
+                )}
+
+                {currentOrg && (
+                    <>
+                        <MaintenanceNotificationCard />
+                        <MaintenanceModeCard />
+                        <RunningWorkspacesCard />
+                    </>
+                )}
+            </div>
+        </div>
+    );
+};
+
+export default AdminPage;

components/dashboard/src/org-admin/MaintenanceModeBanner.tsx

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Gitpod GmbH. All rights reserved.
+ * Licensed under the GNU Affero General Public License (AGPL).
+ * See License.AGPL.txt in the project root for license information.
+ */
+
+import { FC } from "react";
+import Alert from "../components/Alert";
+import { useMaintenanceMode } from "../data/maintenance-mode/maintenance-mode-query";
+
+export const MaintenanceModeBanner: FC = () => {
+    const { isMaintenanceMode } = useMaintenanceMode();
+
+    if (!isMaintenanceMode) {
+        return null;
+    }
+
+    return (
+        <Alert type="warning" className="mb-2">
+            <div className="flex items-center flex-wrap gap-2">
+                <span className="font-semibold">System is in maintenance mode.</span>
+                <span>Starting new workspaces is currently disabled by your organization owner.</span>
+            </div>
+        </Alert>
+    );
+};