Always offer the GitHub App install link

apps/api/src/documentation/github/setup.test.ts

@@ -248,6 +248,8 @@ describe("account-bound GitHub setup proof", () => {
       mock as unknown as DocsGitHubApp,
     );
     expect(result.repositories).toHaveLength(1);
+    // Offered even with an installation, so another organization can be added.
+    expect(result.installUrl).toMatch(/\/installations\/new$/);
     expect(result.installations).toEqual([
       { installationId: 7, accountLogin: "org", accountType: "Organization" },
     ]);

apps/api/src/documentation/github/setup.ts

@@ -205,14 +205,11 @@ export async function listSetupRepositories(
     (input.page ?? 1) > 100
   )
     throw new GitHubDocsError("GITHUB_INVALID_REQUEST", 400);
+  // Always offered: a user with one installation may still need to add an organization.
+  const installUrl = `https://github.com/apps/${encodeURIComponent(config.appSlug)}/installations/new`;
   const installationId = input.installationId ?? installations[0]?.id;
   if (installationId === undefined)
-    return {
-      installations: [],
-      repositories: [],
-      nextPage: null,
-      installUrl: `https://github.com/apps/${encodeURIComponent(config.appSlug)}/installations/new`,
-    };
+    return { installations: [], repositories: [], nextPage: null, installUrl };
   if (!installations.some((i) => i.id === installationId))
     throw new GitHubDocsError("GITHUB_REPOSITORY_NOT_AUTHORIZED", 403);
   const page = input.page ?? 1;
@@ -238,7 +235,7 @@ export async function listSetupRepositories(
         defaultBranch: r.default_branch,
       })),
     nextPage: batch.repositories.length === 100 ? page + 1 : null,
-    installUrl: null,
+    installUrl,
   };
 }
 

apps/web/components/content/documentation-source.tsx

@@ -279,7 +279,7 @@ export function DocumentationSource({
       sessionStorage.removeItem(installRedirectKey);
       return;
     }
-    if (!repositories.installUrl || sessionStorage.getItem(installRedirectKey)) return;
+    if (sessionStorage.getItem(installRedirectKey)) return;
     sessionStorage.setItem(installRedirectKey, "1");
     window.location.assign(repositories.installUrl);
   }, [repositories, installRedirectKey]);
@@ -770,7 +770,7 @@ export function DocumentationSource({
           lead="Pick the GitHub account and repository that will hold your docs or pages."
         />
         {!repositories && <p className="text-muted-foreground text-sm">Loading…</p>}
-        {repositories?.installUrl && (
+        {repositories && repositories.installations.length === 0 && (
           <Callout tone="info" title="No accessible installation yet">
             Install the GitHub App, or wait for organization approval, then refresh the
             list.
@@ -779,7 +779,7 @@ export function DocumentationSource({
                 size="sm"
                 variant="outline"
                 onClick={() =>
-                  window.open(repositories.installUrl!, "_blank", "noopener,noreferrer")
+                  window.open(repositories.installUrl, "_blank", "noopener,noreferrer")
                 }
               >
                 Open App installation
@@ -811,6 +811,10 @@ export function DocumentationSource({
                   ))}
                 </SelectContent>
               </Select>
+              <p className="text-muted-foreground text-xs">
+                Organization missing? Use “Add an organization or account” below. On
+                GitHub, an organization owner installs the app or approves your request.
+              </p>
             </div>
             <div className="space-y-1.5">
               <Label htmlFor="git-repository">Repository</Label>
@@ -849,6 +853,18 @@ export function DocumentationSource({
                 >
                   Refresh list
                 </LinkButton>
+                <LinkButton
+                  disabled={busy}
+                  onClick={() =>
+                    window.open(
+                      repositories.installUrl,
+                      "_blank",
+                      "noopener,noreferrer",
+                    )
+                  }
+                >
+                  Add an organization or account
+                </LinkButton>
                 {repositories.nextPage && (
                   <LinkButton
                     disabled={busy}

packages/api-contract/src/schemas/documentation-github.ts

@@ -175,7 +175,7 @@ export const documentationGitRepositoriesSchema = z.object({
     }),
   ),
   nextPage: z.number().int().positive().nullable(),
-  installUrl: z.string().url().nullable(),
+  installUrl: z.string().url(),
 });
 /** Dry run of a pages folder at the branch head: what would go live. */
 export const gitPagesPreviewSchema = z.object({