@bevel-software/platform-core-backend 0.21.0 → 0.22.0

package/src/modules/settings/__tests__/setup.routes.git-mode.test.ts

@@ -0,0 +1,353 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import type { KbContext } from '../../../shared/kb-context.js';
+import { createSetupRoutes } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import { ManagedRepository } from '../managed-repository.js';
+import { RepositorySource } from '../repository-source.js';
+import type { Database } from '../../database/connection.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { ConnectionCheck, RepositoryConnection } from '../connection-check.js';
+
+const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
+const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'GIT_MODE', 'GITHUB_TOKEN', 'DEFAULT_BRANCH', 'PROTECTED_BRANCHES'] as const;
+
+let server: HttpServer | null = null;
+let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  savedEnv = {};
+  for (const k of KB_ENV) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+});
+
+afterEach(() => {
+  server?.close();
+  server = null;
+  for (const k of KB_ENV) {
+    const original = savedEnv[k];
+    if (original === undefined) delete process.env[k];
+    else process.env[k] = original;
+  }
+});
+
+/**
+ * The setup router with the choice of repository, over settings that are
+ * stored in memory. The managed repository is a stand-in that records being
+ * asked for; the startup phase and the remote are stand-ins that count.
+ */
+function listen(
+  opts: {
+    kb?: KbContext;
+    ensureFails?: boolean;
+    stored?: Record<string, string>;
+    /** The addresses the startup phase cannot reach. */
+    unreachable?: (url: string) => boolean;
+    /** The deployment booted onto a repository it could not reach, and came up gated. */
+    bootFailed?: boolean;
+  } = {},
+) {
+  const db = {
+    select: () => ({ from: () => Promise.resolve([]) }),
+    insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  const settings = new DeploymentSettingsService(db, ENC_KEY);
+  const kb = opts.kb ?? testKbContext({ branchModel: null });
+  const managed = new ManagedRepository('/data/backups/managed-repository');
+  const source = new RepositorySource({ read: (key) => settings.resolve(key), managed });
+  const ensured: string[] = [];
+  const probed: RepositoryConnection[] = [];
+  let phaseRuns = 0;
+  /** The address the startup phase found configured when it ran. */
+  const phaseSaw: string[] = [];
+  /** Stands until the deployment is pointed somewhere the phase can reach. */
+  let bootFailed = opts.bootFailed ?? false;
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userEmail = 'root@example.com';
+    req.userId = 'user-1';
+    next();
+  });
+  app.use(
+    '/api',
+    createSetupRoutes(
+      settings,
+      { isAdmin: async () => true } as IAdminAccessService,
+      {
+        runAll: async () => {
+          phaseRuns += 1;
+          phaseSaw.push(source.url());
+          if (opts.unreachable?.(source.url())) throw new Error(`fatal: repository '${source.url()}' not found`);
+          bootFailed = false;
+        },
+        // A boot that survived an unreachable repository, as the runner reports it.
+        ...(opts.bootFailed ? { lastFailure: () => (bootFailed ? 'fatal: unable to access the repository' : null) } : {}),
+      },
+      kb,
+      undefined,
+      async (connection): Promise<ConnectionCheck> => {
+        probed.push(connection);
+        return { outcome: 'connected', branches: ['main'], defaultBranch: 'main', empty: false };
+      },
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      {
+        source,
+        ensureManaged: async (branch) => {
+          if (opts.ensureFails) throw new Error('EACCES: permission denied, mkdir /data/backups');
+          ensured.push(branch);
+        },
+      },
+    ),
+  );
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  const base = `http://127.0.0.1:${port}`;
+  const save = (entries: Record<string, string>) =>
+    fetch(`${base}/api/setup/settings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ settings: entries }),
+    });
+  const status = async () => (await fetch(`${base}/api/setup/status`)).json() as Promise<Record<string, unknown>>;
+  return { save, status, settings, source, managed, ensured, probed, kb, phase: { runs: () => phaseRuns, saw: phaseSaw } };
+}
+
+const HOSTED = { kbRepoUrl: 'https://git.example.com/acme/kb.git', gitToken: 'the-token' };
+const BRANCHES = { defaultBranch: 'main', protectedBranches: 'main' };
+
+describe('setup status: the choice of repository', () => {
+  it('offers the ways there are, and says none is chosen on a new deployment', async () => {
+    const { status } = listen();
+    expect(await status()).toMatchObject({ complete: false, repository: { mode: null, modes: ['managed', 'token'] } });
+  });
+
+  it('says a deployment configured before there was a choice is on the way it has', async () => {
+    const { status, save } = listen({ kb: testKbContext() });
+    await save({ ...HOSTED, ...BRANCHES });
+    expect(await status()).toMatchObject({ repository: { mode: 'token' } });
+  });
+});
+
+describe('choosing a repository the deployment keeps', () => {
+  it('finishes setup on that choice alone', async () => {
+    const { save, ensured, probed, phase, managed, kb } = listen();
+    const res = await save({ gitMode: 'managed' });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, complete: true, restartRequired: false, repository: { mode: 'managed' } });
+    // The repository was there before the save pointed everything at it,
+    expect(ensured).toEqual(['main']);
+    // no host was asked anything,
+    expect(probed).toEqual([]);
+    // and the startup phase ran against it, on the branches named for it.
+    expect(phase.runs()).toBe(1);
+    expect(phase.saw).toEqual([managed.path]);
+    expect(kb.defaultBranch).toBe('main');
+    expect([...kb.protectedBranches]).toEqual(['main']);
+  });
+
+  it('keeps the branches an admin named over its own', async () => {
+    const { save, ensured, settings } = listen();
+    const res = await save({ gitMode: 'managed', defaultBranch: 'live', protectedBranches: 'live, draft' });
+    expect(res.status).toBe(200);
+    expect(ensured).toEqual(['live']);
+    expect(settings.resolve('defaultBranch')).toBe('live');
+    expect(settings.resolve('protectedBranches')).toBe('live, draft');
+  });
+
+  it('names no branches for any other way: a repository that exists is asked for its own', async () => {
+    const { save, settings } = listen();
+    await save({ ...HOSTED, gitMode: 'token' });
+    expect(settings.resolve('defaultBranch')).toBe('');
+    expect(settings.resolve('protectedBranches')).toBe('');
+  });
+
+  it('refuses the choice when the repository cannot be created, and stores nothing', async () => {
+    const { save, settings, phase } = listen({ ensureFails: true });
+    const res = await save({ gitMode: 'managed' });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string; problems: Record<string, string> };
+    expect(body.problems.gitMode).toMatch(/could not be created/);
+    // What the disk said stays in the log.
+    expect(JSON.stringify(body)).not.toMatch(/EACCES|\/data\/backups/);
+    expect(settings.resolve('gitMode')).toBe('');
+    expect(phase.runs()).toBe(0);
+  });
+
+  it('refuses a way it does not know', async () => {
+    const { save } = listen();
+    const res = await save({ gitMode: 'carrier-pigeon' });
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { problems: Record<string, string> }).problems.gitMode).toMatch(/managed, github-app, token/);
+  });
+});
+
+describe('a deployment that is serving moves to another repository', () => {
+  async function serving() {
+    const mounted = listen({ kb: testKbContext() });
+    await mounted.save({ ...HOSTED, ...BRANCHES });
+    return mounted;
+  }
+
+  it('owes a restart, and says both where it is and where it is going', async () => {
+    const { save, status, phase, ensured } = await serving();
+    const runsBefore = phase.runs();
+    const res = await save({ gitMode: 'managed' });
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, complete: true, restartRequired: true, repository: { mode: 'token', chosen: 'managed' } });
+    expect(await status()).toMatchObject({ complete: true, repository: { mode: 'token', chosen: 'managed' } });
+    expect(ensured).toHaveLength(1);
+    // Sessions may be live: the phase that moves working copies waits for the restart.
+    expect(phase.runs()).toBe(runsBefore);
+  });
+
+  /**
+   * The move is a fact about the NEXT start. Until then every working copy
+   * is a clone of the repository the deployment had, so that is the
+   * repository git is handed the address of, and its token is the one
+   * presented. Reading the mode live moved the process at the save: pushes
+   * went out with no credential, and a branch opened in between was cloned
+   * from a repository nothing had prepared.
+   */
+  it('goes on working against the repository it has until it is started again', async () => {
+    const { save, source } = await serving();
+    await save({ gitMode: 'managed' });
+    expect(source.mode()).toBe('token');
+    expect(source.url()).toBe(HOSTED.kbRepoUrl);
+    expect(source.credentials.token()).toBe('the-token');
+    expect(source.credentials.username()).toBe('x-access-token');
+    // A token rotated meanwhile is still the one the next push carries.
+    await save({ gitToken: 'a-rotated-token' });
+    expect(source.credentials.token()).toBe('a-rotated-token');
+  });
+
+  it('is on the repository it chose once it is started again, and presents it nothing of the old one', async () => {
+    const { save, source, managed } = await serving();
+    await save({ gitMode: 'managed' });
+    // What a restart does: the source is built on the mode chosen.
+    source.takeEffect();
+    expect(source.mode()).toBe('managed');
+    expect(source.url()).toBe(managed.path);
+    expect(source.credentials.token()).toBeNull();
+  });
+
+  it('goes on owing the restart through saves about other things', async () => {
+    const { save } = await serving();
+    await save({ gitMode: 'managed' });
+    const body = (await (await save({ kbSyncSecret: 'a-secret-of-sixteen-or-more' })).json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, restartRequired: true, repository: { mode: 'token', chosen: 'managed' } });
+  });
+
+  it('owes nothing once the move is taken back', async () => {
+    const { save, probed } = await serving();
+    await save({ gitMode: 'managed' });
+    const asked = probed.length;
+    const body = (await (await save({ gitMode: 'token' })).json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, restartRequired: false, repository: { mode: 'token', chosen: 'token' } });
+    // Nothing about the connection changed, so the host is not asked again.
+    expect(probed).toHaveLength(asked);
+  });
+
+  it('owes none for naming the way it was already on', async () => {
+    const { save, probed } = await serving();
+    const asked = probed.length;
+    const body = (await (await save({ gitMode: 'token' })).json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, restartRequired: false, repository: { mode: 'token', chosen: 'token' } });
+    expect(probed).toHaveLength(asked);
+  });
+});
+
+/**
+ * The pin protects what is running on the mode in effect. Behind a shut
+ * gate nothing is, however completely the settings were answered, and a
+ * deployment pinned there could not be got out of a repository that does
+ * not work by choosing one that does.
+ */
+describe('a deployment that answered everything and serves nobody', () => {
+  const isHosted = (url: string) => url === HOSTED.kbRepoUrl;
+
+  it('is got going by choosing another way, when its first initialisation failed', async () => {
+    const { save, status, phase, managed, source } = listen({ kb: testKbContext(), unreachable: isHosted });
+    // First run: an address and a token, accepted, and a first clone that fails.
+    const first = await save({ ...HOSTED, ...BRANCHES });
+    expect(first.status).toBe(500);
+    expect(await status()).toMatchObject({ complete: false, kbInit: expect.any(Object), repository: { mode: 'token' } });
+
+    const second = await save({ gitMode: 'managed' });
+    const body = (await second.json()) as Record<string, unknown>;
+    expect(second.status, JSON.stringify(body)).toBe(200);
+    // The retry ran against the repository that was chosen, not the one that had just failed,
+    expect(phase.saw).toEqual([HOSTED.kbRepoUrl, managed.path]);
+    // nothing is owed, and the gate is open.
+    expect(body).toMatchObject({ complete: true, restartRequired: false, repository: { mode: 'managed', chosen: 'managed' } });
+    expect(source.credentials.token()).toBeNull();
+    expect(await status()).toMatchObject({ complete: true });
+    expect(await status()).not.toHaveProperty('kbInit');
+  });
+
+  it('is got going the same way when it booted onto a repository it could not reach', async () => {
+    Object.assign(process.env, { KB_REPO_URL: HOSTED.kbRepoUrl, GIT_TOKEN: HOSTED.gitToken, DEFAULT_BRANCH: 'main', PROTECTED_BRANCHES: 'main' });
+    const { save, status, phase, managed } = listen({ kb: testKbContext(), bootFailed: true, unreachable: isHosted });
+    expect(await status()).toMatchObject({ complete: false, repository: { mode: 'token' } });
+
+    const body = (await (await save({ gitMode: 'managed' })).json()) as Record<string, unknown>;
+    expect(phase.saw).toEqual([managed.path]);
+    expect(body).toMatchObject({ complete: true, restartRequired: false, repository: { mode: 'managed', chosen: 'managed' } });
+  });
+
+  it('is still asked for a restart once it IS serving: the same save, a different deployment', async () => {
+    const { save, phase } = listen({ kb: testKbContext() });
+    await save({ ...HOSTED, ...BRANCHES });
+    const runs = phase.runs();
+    const body = (await (await save({ gitMode: 'managed' })).json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ complete: true, restartRequired: true, repository: { mode: 'token', chosen: 'managed' } });
+    expect(phase.runs()).toBe(runs);
+  });
+});
+
+describe('a deployment whose way is chosen by the environment', () => {
+  it('says which variable chose', async () => {
+    process.env.GIT_MODE = 'managed';
+    const { status } = listen();
+    expect(await status()).toMatchObject({ repository: { mode: 'managed', chosen: 'managed', pinned: 'GIT_MODE' } });
+  });
+
+  it('says nothing of the kind when the admin chose', async () => {
+    const { save, status } = listen();
+    await save({ gitMode: 'managed' });
+    expect(((await status()) as { repository: object }).repository).not.toHaveProperty('pinned');
+  });
+});
+
+describe('a mount without the choice', () => {
+  it('is the one way there was: an address and a token', async () => {
+    const db = {
+      select: () => ({ from: () => Promise.resolve([]) }),
+      insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+      delete: () => ({ where: () => Promise.resolve() }),
+    } as unknown as Database;
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userEmail = 'root@example.com';
+      next();
+    });
+    app.use('/api', createSetupRoutes(settings, { isAdmin: async () => true } as IAdminAccessService, { runAll: async () => {} }, testKbContext()));
+    server = app.listen(0);
+    const { port } = server.address() as AddressInfo;
+    const status = (await (await fetch(`http://127.0.0.1:${port}/api/setup/status`)).json()) as Record<string, unknown>;
+    expect(status).not.toHaveProperty('repository');
+    expect(status.complete).toBe(false);
+  });
+});

package/src/modules/settings/__tests__/setup.routes.github-app.test.ts

@@ -0,0 +1,282 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import type { KbContext } from '../../../shared/kb-context.js';
+import { createSetupRoutes } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import { ManagedRepository } from '../managed-repository.js';
+import { RepositorySource, type GitHubAppRepository } from '../repository-source.js';
+import type { Database } from '../../database/connection.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { ConnectionCheck, RepositoryConnection } from '../connection-check.js';
+
+const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
+const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'GIT_MODE', 'GITHUB_TOKEN', 'DEFAULT_BRANCH', 'PROTECTED_BRANCHES', 'GITHUB_APP_REPOSITORY'] as const;
+
+let server: HttpServer | null = null;
+let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  savedEnv = {};
+  for (const k of KB_ENV) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+});
+
+afterEach(() => {
+  server?.close();
+  server = null;
+  for (const k of KB_ENV) {
+    const original = savedEnv[k];
+    if (original === undefined) delete process.env[k];
+    else process.env[k] = original;
+  }
+});
+
+type Answer = ConnectionCheck | ((connection: RepositoryConnection) => ConnectionCheck);
+const CONNECTED: ConnectionCheck = { outcome: 'connected', branches: ['trunk', 'draft'], defaultBranch: 'trunk', empty: false };
+
+/**
+ * The setup router over a deployment that has a GitHub App installed (or
+ * not), with GitHub's answer to the connection check given by the suite.
+ */
+function listen(
+  opts: {
+    kb?: KbContext;
+    installed?: boolean;
+    tokenGiven?: boolean;
+    offered?: boolean;
+    github?: Answer;
+    /** What the person who connected GitHub could push to. */
+    permitted?: string[];
+  } = {},
+) {
+  const db = {
+    select: () => ({ from: () => Promise.resolve([]) }),
+    insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  const settings = new DeploymentSettingsService(db, ENC_KEY);
+  const kb = opts.kb ?? testKbContext({ branchModel: null });
+  let prepared = 0;
+  const githubApp: GitHubAppRepository = {
+    url: (read) => (read('githubRepository') ? `https://github.com/${read('githubRepository')}.git` : ''),
+    answered: (read) => (opts.installed ?? true) && Boolean(read('githubRepository')),
+    prepare: async () => {
+      prepared += 1;
+      if (opts.tokenGiven === false) throw new Error('GitHub answered 404');
+    },
+    token: () => (opts.tokenGiven === false || prepared === 0 ? null : 'an-installation-token'),
+    permits: (repository) => (opts.permitted ?? ['acme/kb', 'acme/another']).includes(repository),
+  };
+  const source = new RepositorySource({
+    read: (key) => settings.resolve(key),
+    managed: new ManagedRepository('/data/backups/managed-repository'),
+    githubApp,
+  });
+  const probed: RepositoryConnection[] = [];
+  let phaseRuns = 0;
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userEmail = 'root@example.com';
+    req.userId = 'user-1';
+    next();
+  });
+  app.use(
+    '/api',
+    createSetupRoutes(
+      settings,
+      { isAdmin: async () => true } as IAdminAccessService,
+      { runAll: async () => void (phaseRuns += 1) },
+      kb,
+      undefined,
+      async (connection) => {
+        probed.push(connection);
+        const answer = opts.github ?? CONNECTED;
+        return typeof answer === 'function' ? answer(connection) : answer;
+      },
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      { source, ensureManaged: async () => undefined, ...(opts.offered === false ? {} : { githubApp }) },
+    ),
+  );
+  server = app.listen(0);
+  const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  const save = async (entries: Record<string, string>) => {
+    const res = await fetch(`${base}/api/setup/settings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ settings: entries }),
+    });
+    return { status: res.status, body: (await res.json()) as Record<string, unknown> & { problems?: Record<string, string> } };
+  };
+  const status = async () => (await fetch(`${base}/api/setup/status`)).json() as Promise<Record<string, unknown>>;
+  return { save, status, settings, source, probed, kb, phaseRuns: () => phaseRuns };
+}
+
+const CHOICE = { gitMode: 'github-app', githubRepository: 'acme/kb' };
+
+describe('setup status: GitHub as a way of having a repository', () => {
+  it('is offered second, by a deployment that can connect to it', async () => {
+    expect(await listen().status()).toMatchObject({ repository: { mode: null, modes: ['managed', 'github-app', 'token'] } });
+  });
+
+  it('is not offered by one that cannot', async () => {
+    expect(await listen({ offered: false }).status()).toMatchObject({ repository: { modes: ['managed', 'token'] } });
+  });
+});
+
+describe('choosing a repository on GitHub', () => {
+  it('finishes setup once GitHub accepts the installation for reading and writing', async () => {
+    const { save, probed, settings, kb, phaseRuns, source } = listen();
+    const { status, body } = await save(CHOICE);
+    expect(status, JSON.stringify(body)).toBe(200);
+    expect(body).toMatchObject({ ok: true, complete: true, restartRequired: false, repository: { mode: 'github-app' } });
+    // Asked with what git will present: the installation's token, never a stored one.
+    expect(probed).toEqual([{ url: 'https://github.com/acme/kb.git', token: 'an-installation-token', username: 'x-access-token' }]);
+    expect(source.url()).toBe('https://github.com/acme/kb.git');
+    expect(settings.resolve('githubRepository')).toBe('acme/kb');
+    expect(phaseRuns()).toBe(1);
+    // The repository said what it calls its trunk.
+    expect(kb.defaultBranch).toBe('trunk');
+    expect([...kb.protectedBranches]).toEqual(['trunk']);
+  });
+
+  it('names the usual branch for a repository that is empty', async () => {
+    const { save, kb } = listen({ github: { outcome: 'connected', branches: [], defaultBranch: null, empty: true } });
+    expect((await save(CHOICE)).status).toBe(200);
+    expect(kb.defaultBranch).toBe('main');
+  });
+
+  it('keeps the branches an admin named over the repository trunk', async () => {
+    const { save, settings } = listen();
+    await save({ ...CHOICE, defaultBranch: 'live', protectedBranches: 'live, draft' });
+    expect(settings.resolve('defaultBranch')).toBe('live');
+    expect(settings.resolve('protectedBranches')).toBe('live, draft');
+  });
+
+  /**
+   * The name is the one part of this connection an admin types, and the
+   * installation's token would answer for any repository the installation
+   * covers. So the name is held to what the person who connected GitHub
+   * could push to with their own account, BEFORE that token is used for
+   * anything: GitHub is not asked, so nothing about the repository, not
+   * even that it exists, comes back.
+   */
+  it('refuses a repository the person who connected GitHub could not push to, without asking GitHub', async () => {
+    const { save, settings, probed, phaseRuns } = listen({ permitted: ['x/docs'] });
+    for (const name of ['x/payroll', 'x/handbook', 'someone-else/secrets']) {
+      const { status, body } = await save({ gitMode: 'github-app', githubRepository: name });
+      expect(status, name).toBe(400);
+      expect(body.problems?.githubRepository, name).toMatch(/your own GitHub account can write to/);
+    }
+    expect(probed).toEqual([]);
+    expect(settings.resolve('githubRepository')).toBe('');
+    expect(settings.resolve('gitMode')).toBe('');
+    expect(phaseRuns()).toBe(0);
+    // The one they can push to is theirs to connect.
+    expect((await save({ gitMode: 'github-app', githubRepository: 'x/docs' })).status).toBe(200);
+  });
+
+  it('refuses a repository the installation no longer reaches, and stores nothing', async () => {
+    const { save, settings, phaseRuns } = listen({
+      github: { outcome: 'rejected', reason: 'not-found', field: 'kbRepoUrl', error: 'repository not found' },
+    });
+    const { status, body } = await save({ gitMode: 'github-app', githubRepository: 'acme/kb' });
+    expect(status).toBe(400);
+    expect(body.problems).toEqual({
+      githubRepository: 'The GitHub App cannot reach that repository. Add the repository to the app’s installation on GitHub.',
+    });
+    expect(settings.resolve('githubRepository')).toBe('');
+    expect(settings.resolve('gitMode')).toBe('');
+    expect(phaseRuns()).toBe(0);
+  });
+
+  it.each([
+    [
+      'it may read and not write',
+      { outcome: 'read-only', field: 'gitToken', error: 'x', branches: ['main'], defaultBranch: 'main', empty: false } as ConnectionCheck,
+      /can read that repository but not write/,
+    ],
+    [
+      'GitHub cannot be reached',
+      { outcome: 'rejected', reason: 'unreachable', field: 'kbRepoUrl', error: 'x' } as ConnectionCheck,
+      /could not be reached/,
+    ],
+  ])('says so when %s', async (_why, github, said) => {
+    const { save } = listen({ github });
+    const { status, body } = await save(CHOICE);
+    expect(status).toBe(400);
+    expect(body.problems?.githubRepository).toMatch(said);
+  });
+
+  it('asks for the connection before a repository can be chosen', async () => {
+    const { save, probed } = listen({ installed: false });
+    const { status, body } = await save(CHOICE);
+    expect(status).toBe(400);
+    expect(body.problems).toEqual({ githubRepository: 'Connect GitHub before choosing a repository.' });
+    expect(probed).toEqual([]);
+  });
+
+  it('asks for the repository when only the way was chosen', async () => {
+    const { save } = listen();
+    const { status, body } = await save({ gitMode: 'github-app' });
+    expect(status).toBe(400);
+    expect(body.problems).toEqual({ githubRepository: 'Choose the repository the knowledge base lives in.' });
+  });
+
+  it('says the app may have been uninstalled when GitHub gives no token', async () => {
+    const { save, probed } = listen({ tokenGiven: false });
+    const { status, body } = await save(CHOICE);
+    expect(status).toBe(400);
+    expect(body.problems?.gitMode).toMatch(/may have been uninstalled/);
+    expect(probed).toEqual([]);
+  });
+
+  it('refuses the way on a deployment that does not offer it', async () => {
+    const { save } = listen({ offered: false });
+    const { status, body } = await save(CHOICE);
+    expect(status).toBe(400);
+    expect(body.problems?.gitMode).toMatch(/cannot connect to GitHub/);
+  });
+
+  it('refuses a name that is not a repository', async () => {
+    const { save, probed } = listen();
+    for (const name of ['acme', 'acme/kb.git', '../acme/kb', 'https://github.com/acme/kb', 'acme/kb/extra']) {
+      const { status, body } = await save({ gitMode: 'github-app', githubRepository: name });
+      expect(status, name).toBe(400);
+      expect(body.problems?.githubRepository, name).toBe('Name the repository as owner/name.');
+    }
+    expect(probed).toEqual([]);
+  });
+});
+
+describe('a deployment on GitHub that is serving', () => {
+  async function serving() {
+    const mounted = listen({ kb: testKbContext() });
+    await mounted.save({ ...CHOICE, defaultBranch: 'main', protectedBranches: 'main' });
+    return mounted;
+  }
+
+  it('is not asked about its repository by a save that changes something else', async () => {
+    const { save, probed } = await serving();
+    const asked = probed.length;
+    expect((await save({ kbSyncSecret: 'a-secret-of-sixteen-or-more' })).status).toBe(200);
+    expect(probed).toHaveLength(asked);
+  });
+
+  it('is asked again when it moves to another repository', async () => {
+    const { save, probed } = await serving();
+    const asked = probed.length;
+    const { status } = await save({ githubRepository: 'acme/another' });
+    expect(status).toBe(200);
+    expect(probed).toHaveLength(asked + 1);
+    expect(probed.at(-1)!.url).toBe('https://github.com/acme/another.git');
+  });
+});