Merge pull request #398 from nazarli-shabnam/feat/app-perm-consent-add-install

feat(ui): make connecting additional GitHub accounts/orgs discoverable

Author: nazarli-shabnam

apps/ui/app/settings/page.tsx

@@ -402,7 +402,8 @@ function ConnectedOrgsSection() {
       <div className="border-t border-border p-4">
         {installUrl ? (
           <Button onClick={() => { window.location.href = installUrl }}>
-            <ArrowSquareOut className="size-3.5" />Install GitHub App
+            <ArrowSquareOut className="size-3.5" />
+            {rows.length > 0 ? "Install on another account or org" : "Install GitHub App"}
           </Button>
         ) : (
           <p className="text-xs text-muted-foreground">

apps/ui/components/app-sidebar.tsx

@@ -69,7 +69,7 @@ function ProfileDropdown({
   scopeOptions,
   activeScope,
   onSelectScope,
-  personalInstallUrl,
+  addInstallUrl,
   inviteHref,
   onClose,
   onSignOut,
@@ -78,7 +78,7 @@ function ProfileDropdown({
   scopeOptions: ScopeOption[]
   activeScope: ActiveScope | null
   onSelectScope: (scope: ActiveScope) => void
-  personalInstallUrl: string | null
+  addInstallUrl: string | null
   inviteHref: string
   onClose: () => void
   onSignOut: () => void
@@ -118,10 +118,10 @@ function ProfileDropdown({
       </div>
 
       {/* Scope switcher — personal account + orgs you belong to */}
-      {(scopeOptions.length > 0 || personalInstallUrl) && (
+      {(scopeOptions.length > 0 || addInstallUrl) && (
         <div className="px-1.5 pb-1.5 border-b border-sidebar-border/60">
           <p className="px-2 pt-1 pb-1.5 text-[0.6875rem] font-medium uppercase tracking-wide text-sidebar-foreground/40">
-            Switch account
+            {scopeOptions.length > 0 ? "Switch account" : "Connect account"}
           </p>
           {scopeOptions.map((opt) => {
             const isActive =
@@ -140,13 +140,17 @@ function ProfileDropdown({
               </button>
             )
           })}
-          {personalInstallUrl && (
+          {addInstallUrl && (
             <a
-              href={personalInstallUrl}
+              href={addInstallUrl}
               className="flex items-center gap-2 px-2 py-1.5 text-left rounded-md hover:bg-sidebar-accent/60 transition-colors text-sidebar-foreground/70 hover:text-sidebar-foreground"
             >
               <User className="size-3.5 shrink-0" />
-              <span className="text-[0.8125rem] flex-1">Connect your personal GitHub account</span>
+              <span className="text-[0.8125rem] flex-1">
+                {scopeOptions.some((o) => o.scope.kind === "personal")
+                  ? "Add another account or org"
+                  : "Connect your personal GitHub account"}
+              </span>
               <ArrowSquareOut className="size-3 shrink-0" />
             </a>
           )}
@@ -217,7 +221,9 @@ export function AppSidebar() {
   })
   const personalInstall = installs.find((i) => i.account_type === "User")
   const slug = process.env.NEXT_PUBLIC_GITHUB_APP_SLUG
-  const personalInstallUrl = !personalInstall && slug ? `https://github.com/apps/${slug}/installations/new` : null
+  // Always offer a way to install the App on another account/org (there's no cap on how
+  // many an org admin can connect) — not only when the user has no personal install yet.
+  const addInstallUrl = slug ? `https://github.com/apps/${slug}/installations/new` : null
 
   const scopeOptions: ScopeOption[] = useMemo(
     () => [
@@ -344,7 +350,7 @@ export function AppSidebar() {
             scopeOptions={scopeOptions}
             activeScope={scope}
             onSelectScope={setScope}
-            personalInstallUrl={personalInstallUrl}
+            addInstallUrl={addInstallUrl}
             inviteHref={inviteHref}
             onClose={() => setOpen(false)}
             onSignOut={() => { logout(); setOpen(false); router.replace("/login") }}

apps/ui/tests/components/app-sidebar.test.tsx

@@ -511,6 +511,34 @@ describe("AppSidebar scope switcher", () => {
     expect(connectLink).toHaveAttribute("href", "https://github.com/apps/clevis/installations/new");
   });
 
+  it("shows a 'Connect account' heading instead of 'Switch account' when there's nothing to switch between", async () => {
+    vi.stubEnv("NEXT_PUBLIC_GITHUB_APP_SLUG", "clevis");
+    orgMemberships = [];
+    installations = [];
+    renderSidebar();
+
+    fireEvent.click(screen.getByRole("button", { name: /user/i }));
+
+    await screen.findByRole("link", { name: /connect your personal github account/i });
+    expect(screen.getByText("Connect account")).toBeInTheDocument();
+    expect(screen.queryByText("Switch account")).not.toBeInTheDocument();
+  });
+
+  it("offers 'add another account or org' even when a personal installation already exists", async () => {
+    vi.stubEnv("NEXT_PUBLIC_GITHUB_APP_SLUG", "clevis");
+    installations = [
+      { id: 1, account_login: "octocat", account_type: "User", installation_id: 5, created_at: "2026-01-01T00:00:00Z" },
+    ];
+    renderSidebar();
+
+    fireEvent.click(screen.getByRole("button", { name: /user/i }));
+
+    const addLink = await screen.findByRole("link", { name: /add another account or org/i });
+    expect(addLink).toHaveAttribute("href", "https://github.com/apps/clevis/installations/new");
+    // A switchable option (the personal account) exists here, so the original heading holds.
+    expect(screen.getByText("Switch account")).toBeInTheDocument();
+  });
+
   // Issue #371
   it("auto-selects the sole org membership as the active scope when nothing is persisted", async () => {
     orgMemberships = [{ org_login: "acme", role: "admin" }];

apps/ui/tests/components/settings-page.test.tsx

@@ -339,6 +339,21 @@ describe("SettingsPage", () => {
     });
   });
 
+  it("relabels the install button once an account is already connected", async () => {
+    vi.stubEnv("NEXT_PUBLIC_GITHUB_APP_SLUG", "clevis");
+    orgsMineMock.mockResolvedValue([]);
+    installationsListMock.mockResolvedValue([
+      { id: 1, account_login: "shabnam", account_type: "User", installation_id: 7, created_at: "2026-01-01T00:00:00Z" },
+    ]);
+    tokensListMock.mockResolvedValue([]);
+    configGetAllMock.mockResolvedValue({ worker_poll_seconds: "5", registration_enabled: "true" });
+
+    renderPage();
+
+    expect(await screen.findByRole("button", { name: /install on another account or org/i })).toBeInTheDocument();
+    vi.unstubAllEnvs();
+  });
+
   it("lists both personal and admin-org installations, and disconnects one after a confirm click", async () => {
     orgsMineMock.mockResolvedValue([{ org_login: "acme", role: "admin" }]);
     installationsListMock.mockResolvedValue([

docs/self-hosting.md

@@ -38,6 +38,10 @@ This is the infrastructure/ops guide — getting the Clevis stack itself running
 
    **If your GitHub App was registered before the Setup URL field above was documented here:** open the App's settings on github.com, go to the "Post installation" section, and add the Setup URL now. Orgs that already completed installation don't need to reinstall — only new installs and updates will use the new callback page going forward.
 
+   **Connecting more than one account/org:** there's no limit — install the App from the sidebar's "Switch account" menu or the Settings → Connected GitHub accounts button as many times as you need. Connecting an organization requires you to be a GitHub **owner** of it (Clevis live-checks this against GitHub); if you're only a member, ask an owner to connect it.
+
+   **After the App's permissions are widened:** when a new Clevis release adds an optional write automation (issues #286–#291), existing installations keep working but the new feature stays blocked until a GitHub org owner re-approves the App's updated permission request. Clevis shows affected org admins a "N automations need extra GitHub access" notice in Settings and on the Automation page with a "Review on GitHub" link; the notice clears automatically once the owner approves (via the `installation` `new_permissions_accepted` webhook).
+
 4. (Optional) Configure SMTP so self-registered accounts can verify their email: set `SMTP_HOST`, `SMTP_PORT` (default `587`), `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM` in `.env`. Without these, registration still works — accounts are created immediately — but they stay unverified and can't accept an org invitation until either SMTP is configured and the user clicks the emailed link, or they link a GitHub account instead (GitHub-verified emails are trusted immediately). Accounts created via first-run `/auth/setup` or "Sign in with GitHub" are always verified, regardless of SMTP.
 
 5. (Optional) Give the worker its own Postgres credential, separate from the API's `DB_USER`/`DB_PASSWORD`: set `WORKER_DB_PASSWORD` in `.env`. This is a prerequisite for a future Row-Level Security migration (issue #190) and has no effect otherwise — the worker keeps working exactly as before if left unset. It only takes effect via the `db` container's first-ever startup (`docker-entrypoint-initdb.d` scripts only run once, against a fresh, empty data volume). If you're setting this on an **existing** deployment (a `db` volume that's already initialized), run this once by hand instead: