@shipfox/api-integration-github 2.0.0

package/src/api/shared-installation-token-cache.test.ts

@@ -0,0 +1,294 @@
+import {GithubIntegrationProviderError} from '#core/errors.js';
+import {
+  backoffActive,
+  encodeInstallationTokenEnvelope,
+  needsRefresh,
+  stillValid,
+  TOKEN_REFRESH_MARGIN_MS,
+  TOKEN_VALIDITY_BUFFER_MS,
+} from './installation-token-envelope.js';
+import {
+  type InstallationTokenLockResult,
+  type InstallationTokenSecretStore,
+  SharedInstallationTokenCache,
+} from './shared-installation-token-cache.js';
+
+const workspaceId = '00000000-0000-4000-8000-000000000001';
+const installationId = 123;
+
+function token(tokenValue: string, expiresAt = '2026-06-10T12:00:00.000Z') {
+  return {token: tokenValue, expiresAt: new Date(expiresAt)};
+}
+
+function createStore(): InstallationTokenSecretStore & {
+  values: Map<string, string>;
+  failWrites: boolean;
+} {
+  const values = new Map<string, string>();
+  const store = {
+    values,
+    failWrites: false,
+    read(readWorkspaceId: string, readInstallationId: number) {
+      return Promise.resolve(values.get(`${readWorkspaceId}:${readInstallationId}`) ?? null);
+    },
+    write(
+      writeWorkspaceId: string,
+      writeInstallationId: number,
+      envelope: Parameters<InstallationTokenSecretStore['write']>[2],
+    ) {
+      if (store.failWrites) return Promise.reject(new Error('write failed'));
+      values.set(
+        `${writeWorkspaceId}:${writeInstallationId}`,
+        encodeInstallationTokenEnvelope(envelope),
+      );
+      return Promise.resolve();
+    },
+  };
+  return store;
+}
+
+function cache(
+  options: {
+    store?: InstallationTokenSecretStore | undefined;
+    now?: Date | undefined;
+    withLock?:
+      | (<T>(
+          installationId: number,
+          fn: () => Promise<T>,
+        ) => Promise<InstallationTokenLockResult<T>>)
+      | undefined;
+    resolveWorkspaceId?: ((installationId: number) => Promise<string>) | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+    pollDelaysMs?: number[] | undefined;
+  } = {},
+) {
+  return new SharedInstallationTokenCache({
+    secretStore: options.store ?? createStore(),
+    withLock: options.withLock ?? (async (_id, fn) => ({acquired: true, value: await fn()})),
+    resolveWorkspaceId: options.resolveWorkspaceId ?? (() => Promise.resolve(workspaceId)),
+    now: () => options.now ?? new Date('2026-06-10T11:00:00.000Z'),
+    sleep: options.sleep ?? (() => Promise.resolve()),
+    pollDelaysMs: options.pollDelaysMs ?? [],
+  });
+}
+
+function setEnvelope(
+  store: {values: Map<string, string>},
+  envelope: Parameters<typeof encodeInstallationTokenEnvelope>[0],
+) {
+  store.values.set(`${workspaceId}:${installationId}`, encodeInstallationTokenEnvelope(envelope));
+}
+
+describe('SharedInstallationTokenCache', () => {
+  it('mints once on a cold winner miss and writes the secret envelope', async () => {
+    const store = createStore();
+    const mint = vi.fn(() => Promise.resolve(token('ghs_new')));
+    const shared = cache({store});
+
+    const result = await shared.getOrMint(installationId, mint);
+
+    expect(result).toEqual(token('ghs_new'));
+    expect(mint).toHaveBeenCalledTimes(1);
+    expect(store.values.get(`${workspaceId}:${installationId}`)).toContain('ghs_new');
+  });
+
+  it('returns a warm store hit without minting', async () => {
+    const store = createStore();
+    setEnvelope(store, token('ghs_cached'));
+    const mint = vi.fn(() => Promise.resolve(token('ghs_new')));
+    const shared = cache({store});
+
+    const result = await shared.getOrMint(installationId, mint);
+
+    expect(result).toEqual(token('ghs_cached'));
+    expect(mint).not.toHaveBeenCalled();
+  });
+
+  it('serves a still-valid token on a contended refresh path', async () => {
+    const store = createStore();
+    setEnvelope(store, token('ghs_stale_but_valid', '2026-06-10T11:04:30.000Z'));
+    const mint = vi.fn(() => Promise.resolve(token('ghs_new')));
+    const shared = cache({
+      store,
+      withLock: () => Promise.resolve({acquired: false}),
+    });
+
+    const result = await shared.getOrMint(installationId, mint);
+
+    expect(result).toEqual(token('ghs_stale_but_valid', '2026-06-10T11:04:30.000Z'));
+    expect(mint).not.toHaveBeenCalled();
+  });
+
+  it('polls for the winner commit on a contended cold miss', async () => {
+    const store = createStore();
+    const mint = vi.fn(() => Promise.resolve(token('ghs_new')));
+    let polls = 0;
+    const shared = cache({
+      store,
+      withLock: () => Promise.resolve({acquired: false}),
+      pollDelaysMs: [1, 1],
+      sleep: () => {
+        polls += 1;
+        if (polls === 1) setEnvelope(store, token('ghs_committed'));
+        return Promise.resolve();
+      },
+    });
+
+    const result = await shared.getOrMint(installationId, mint);
+
+    expect(result).toEqual(token('ghs_committed'));
+    expect(mint).not.toHaveBeenCalled();
+  });
+
+  it('refreshes a near-expiry token and clears backoff', async () => {
+    const store = createStore();
+    setEnvelope(store, {
+      ...token('ghs_old', '2026-06-10T11:04:00.000Z'),
+      backoffUntil: new Date('2026-06-10T10:00:00.000Z'),
+      backoffReason: 'rate-limited',
+    });
+    const shared = cache({store});
+
+    const result = await shared.getOrMint(installationId, () => Promise.resolve(token('ghs_new')));
+
+    expect(result).toEqual(token('ghs_new'));
+    expect(store.values.get(`${workspaceId}:${installationId}`)).not.toContain('backoff');
+  });
+
+  it('records transient backoff and short-circuits the next call with the stored reason', async () => {
+    const store = createStore();
+    const mint = vi
+      .fn()
+      .mockRejectedValue(new GithubIntegrationProviderError('rate-limited', 'rate limited', 42));
+    const shared = cache({store});
+
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'rate-limited',
+    });
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'rate-limited',
+      retryAfterSeconds: 42,
+    });
+
+    expect(mint).toHaveBeenCalledTimes(1);
+  });
+
+  it('records terminal backoff without hiding access denied as provider unavailable', async () => {
+    const store = createStore();
+    const mint = vi
+      .fn()
+      .mockRejectedValue(new GithubIntegrationProviderError('access-denied', 'denied'));
+    const shared = cache({store});
+
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'access-denied',
+    });
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'access-denied',
+    });
+
+    expect(mint).toHaveBeenCalledTimes(1);
+  });
+
+  it('serves stale when refresh minting fails while the token is still valid', async () => {
+    const store = createStore();
+    setEnvelope(store, token('ghs_existing', '2026-06-10T11:04:30.000Z'));
+    const shared = cache({store});
+
+    const result = await shared.getOrMint(installationId, () =>
+      Promise.reject(new GithubIntegrationProviderError('provider-unavailable', 'down')),
+    );
+
+    expect(result).toEqual(token('ghs_existing', '2026-06-10T11:04:30.000Z'));
+  });
+
+  it('does not serve stale when refresh minting fails with a terminal reason', async () => {
+    const store = createStore();
+    setEnvelope(store, token('ghs_existing', '2026-06-10T11:04:30.000Z'));
+    const shared = cache({store});
+
+    await expect(
+      shared.getOrMint(installationId, () =>
+        Promise.reject(new GithubIntegrationProviderError('access-denied', 'denied')),
+      ),
+    ).rejects.toMatchObject({reason: 'access-denied'});
+  });
+
+  it('does not serve stale from active terminal backoff on a contended refresh', async () => {
+    const store = createStore();
+    setEnvelope(store, {
+      ...token('ghs_existing', '2026-06-10T11:04:30.000Z'),
+      backoffUntil: new Date('2026-06-10T11:15:00.000Z'),
+      backoffReason: 'installation-not-found',
+    });
+    const shared = cache({
+      store,
+      withLock: () => Promise.resolve({acquired: false}),
+    });
+
+    await expect(
+      shared.getOrMint(installationId, () => Promise.resolve(token('ghs_new'))),
+    ).rejects.toMatchObject({reason: 'installation-not-found'});
+  });
+
+  it('returns a minted token when the cache write fails', async () => {
+    const store = createStore();
+    store.failWrites = true;
+    const shared = cache({store});
+
+    const result = await shared.getOrMint(installationId, () => Promise.resolve(token('ghs_new')));
+
+    expect(result).toEqual(token('ghs_new'));
+  });
+
+  it('treats an invalid envelope as a miss and overwrites it', async () => {
+    const store = createStore();
+    store.values.set(`${workspaceId}:${installationId}`, '{bad json');
+    const shared = cache({store});
+
+    const result = await shared.getOrMint(installationId, () => Promise.resolve(token('ghs_new')));
+
+    expect(result).toEqual(token('ghs_new'));
+    expect(store.values.get(`${workspaceId}:${installationId}`)).toContain('ghs_new');
+  });
+
+  it('surfaces an unresolvable installation as installation-not-found', async () => {
+    const shared = cache({
+      resolveWorkspaceId: () =>
+        Promise.reject(new GithubIntegrationProviderError('installation-not-found', 'missing')),
+    });
+
+    await expect(
+      shared.getOrMint(installationId, () => Promise.resolve(token('ghs_new'))),
+    ).rejects.toMatchObject({reason: 'installation-not-found'});
+  });
+});
+
+describe('installation token envelope predicates', () => {
+  it('uses exact refresh, validity, and backoff boundaries', () => {
+    const now = new Date('2026-06-10T11:00:00.000Z');
+
+    expect(needsRefresh(new Date(now.getTime() + TOKEN_REFRESH_MARGIN_MS), now)).toBe(true);
+    expect(needsRefresh(new Date(now.getTime() + TOKEN_REFRESH_MARGIN_MS + 1), now)).toBe(false);
+    expect(stillValid(new Date(now.getTime() + TOKEN_VALIDITY_BUFFER_MS), now)).toBe(false);
+    expect(stillValid(new Date(now.getTime() + TOKEN_VALIDITY_BUFFER_MS + 1), now)).toBe(true);
+    expect(
+      backoffActive(
+        {
+          backoffUntil: now,
+          backoffReason: 'provider-unavailable',
+        },
+        now,
+      ),
+    ).toBe(false);
+    expect(
+      backoffActive(
+        {
+          backoffUntil: new Date(now.getTime() + 1),
+          backoffReason: 'provider-unavailable',
+        },
+        now,
+      ),
+    ).toBe(true);
+  });
+});

package/src/api/shared-installation-token-cache.ts

@@ -0,0 +1,346 @@
+import {setTimeout as sleepTimeout} from 'node:timers/promises';
+import {logger} from '@shipfox/node-opentelemetry';
+import {GithubIntegrationProviderError} from '#core/errors.js';
+import {
+  recordInstallationTokenBackoff,
+  recordInstallationTokenLookup,
+  recordInstallationTokenMint,
+} from '#metrics/index.js';
+import type {GithubInstallationAccessToken} from './client.js';
+import {
+  backoffActive,
+  backoffMs,
+  classifyMintError,
+  type InstallationTokenEnvelope,
+  mintErrorClassForReason,
+  parseInstallationTokenEnvelope,
+  providerErrorFromBackoff,
+  stillValid,
+  toProviderError,
+  usable,
+} from './installation-token-envelope.js';
+
+export interface InstallationTokenCache {
+  getOrMint(
+    installationId: number,
+    mint: () => Promise<GithubInstallationAccessToken>,
+  ): Promise<GithubInstallationAccessToken>;
+}
+
+export type InstallationTokenLockResult<T> = {acquired: true; value: T} | {acquired: false};
+
+export interface InstallationTokenSecretStore {
+  read(workspaceId: string, installationId: number): Promise<string | null>;
+  write(
+    workspaceId: string,
+    installationId: number,
+    envelope: InstallationTokenEnvelope,
+  ): Promise<void>;
+}
+
+export interface SharedInstallationTokenCacheOptions {
+  secretStore: InstallationTokenSecretStore;
+  withLock: <T>(
+    installationId: number,
+    fn: () => Promise<T>,
+  ) => Promise<InstallationTokenLockResult<T>>;
+  resolveWorkspaceId: (installationId: number) => Promise<string>;
+  now?: (() => Date) | undefined;
+  sleep?: ((ms: number) => Promise<void>) | undefined;
+  pollDelaysMs?: number[] | undefined;
+  workspaceCacheTtlMs?: number | undefined;
+  mintTimeoutMs?: number | undefined;
+}
+
+const DEFAULT_POLL_DELAYS_MS = [100, 200, 400, 500, 800];
+const DEFAULT_WORKSPACE_CACHE_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_MINT_TIMEOUT_MS = 30 * 1000;
+
+export class SharedInstallationTokenCache implements InstallationTokenCache {
+  private readonly workspaceIds = new Map<number, {workspaceId: string; expiresAtMs: number}>();
+  private readonly now: () => Date;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly pollDelaysMs: number[];
+  private readonly workspaceCacheTtlMs: number;
+  private readonly mintTimeoutMs: number;
+
+  constructor(private readonly options: SharedInstallationTokenCacheOptions) {
+    this.now = options.now ?? (() => new Date());
+    this.sleep = options.sleep ?? ((ms) => sleepTimeout(ms).then(() => undefined));
+    this.pollDelaysMs = options.pollDelaysMs ?? DEFAULT_POLL_DELAYS_MS;
+    this.workspaceCacheTtlMs = options.workspaceCacheTtlMs ?? DEFAULT_WORKSPACE_CACHE_TTL_MS;
+    this.mintTimeoutMs = options.mintTimeoutMs ?? DEFAULT_MINT_TIMEOUT_MS;
+  }
+
+  async getOrMint(
+    installationId: number,
+    mint: () => Promise<GithubInstallationAccessToken>,
+  ): Promise<GithubInstallationAccessToken> {
+    const workspaceId = await this.resolveWorkspaceId(installationId);
+    const envelope = await this.readEnvelope(workspaceId, installationId);
+    if (usable(envelope, this.now())) {
+      recordInstallationTokenLookup('db-hit');
+      return tokenFromEnvelope(envelope);
+    }
+
+    const result = await this.options.withLock(installationId, () =>
+      this.mintUnderLock({workspaceId, installationId, mint}),
+    );
+    if (result.acquired) return result.value;
+
+    return await this.serveStaleOrPoll({workspaceId, installationId, envelope});
+  }
+
+  private async mintUnderLock(params: {
+    workspaceId: string;
+    installationId: number;
+    mint: () => Promise<GithubInstallationAccessToken>;
+  }): Promise<GithubInstallationAccessToken> {
+    const envelope = await this.readEnvelope(params.workspaceId, params.installationId);
+    const now = this.now();
+    if (usable(envelope, now)) {
+      recordInstallationTokenLookup('db-hit');
+      return tokenFromEnvelope(envelope);
+    }
+
+    if (activeBackoff(envelope, now)) {
+      if (canServeStale(envelope, now)) {
+        recordInstallationTokenLookup('served-stale');
+        return tokenFromEnvelope(envelope);
+      }
+      recordInstallationTokenLookup('backoff');
+      throw providerErrorFromBackoff(
+        envelope?.backoffReason ?? 'provider-unavailable',
+        (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),
+      );
+    }
+
+    let token: GithubInstallationAccessToken;
+    try {
+      token = await this.recordMint(params.mint);
+    } catch (error) {
+      const providerError = toProviderError(error);
+      const classified = classifyMintError(providerError);
+      const until = new Date(this.now().getTime() + backoffMs(classified));
+      recordInstallationTokenBackoff({reason: classified.reason, class: classified.class});
+
+      await this.writeEnvelope(params.workspaceId, params.installationId, {
+        token: envelope?.token,
+        expiresAt: envelope?.expiresAt,
+        permissions: envelope?.permissions,
+        backoffUntil: until,
+        backoffReason: classified.reason,
+      }).catch((writeError) => {
+        logger().warn(
+          {installationId: params.installationId, reason: classified.reason, error: writeError},
+          'github installation token backoff write failed',
+        );
+      });
+
+      if (
+        classified.class === 'transient' &&
+        envelope?.token &&
+        stillValid(envelope.expiresAt, this.now())
+      ) {
+        logger().warn(
+          {
+            installationId: params.installationId,
+            expiresAt: envelope.expiresAt?.toISOString(),
+            reason: classified.reason,
+            backoffUntil: until.toISOString(),
+          },
+          'github installation token mint failed; serving stale token',
+        );
+        recordInstallationTokenLookup('served-stale');
+        return tokenFromEnvelope(envelope);
+      }
+
+      logger().warn(
+        {
+          installationId: params.installationId,
+          reason: classified.reason,
+          backoffUntil: until.toISOString(),
+          error: providerError,
+        },
+        'github installation token mint failed; backoff recorded',
+      );
+      recordInstallationTokenLookup('backoff');
+      throw providerError;
+    }
+
+    try {
+      await this.writeEnvelope(params.workspaceId, params.installationId, {
+        token: token.token,
+        expiresAt: token.expiresAt,
+        permissions: token.permissions,
+      });
+    } catch (error) {
+      logger().warn(
+        {installationId: params.installationId, expiresAt: token.expiresAt.toISOString(), error},
+        'github installation token cache write failed after mint',
+      );
+    }
+
+    logger().info(
+      {installationId: params.installationId, expiresAt: token.expiresAt.toISOString()},
+      'github installation token minted',
+    );
+    recordInstallationTokenLookup('minted');
+    return token;
+  }
+
+  private async serveStaleOrPoll(params: {
+    workspaceId: string;
+    installationId: number;
+    envelope: InstallationTokenEnvelope | undefined;
+  }): Promise<GithubInstallationAccessToken> {
+    const initialNow = this.now();
+    if (canServeStale(params.envelope, initialNow)) {
+      recordInstallationTokenLookup('served-stale');
+      return tokenFromEnvelope(params.envelope);
+    }
+    if (activeBackoff(params.envelope, initialNow)) {
+      recordInstallationTokenLookup('backoff');
+      throw providerErrorFromBackoff(
+        params.envelope.backoffReason,
+        params.envelope.backoffUntil.getTime() - initialNow.getTime(),
+      );
+    }
+
+    for (const delayMs of this.pollDelaysMs) {
+      await this.sleep(delayMs);
+      const envelope = await this.readEnvelope(params.workspaceId, params.installationId);
+      const now = this.now();
+      if (usable(envelope, now)) {
+        recordInstallationTokenLookup('contended-poll');
+        return tokenFromEnvelope(envelope);
+      }
+      if (backoffActive(envelope, now)) {
+        recordInstallationTokenLookup('backoff');
+        throw providerErrorFromBackoff(
+          envelope?.backoffReason ?? 'provider-unavailable',
+          (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),
+        );
+      }
+    }
+
+    throw new GithubIntegrationProviderError(
+      'provider-unavailable',
+      'GitHub installation token mint is still in progress',
+      1,
+    );
+  }
+
+  private async recordMint(
+    mint: () => Promise<GithubInstallationAccessToken>,
+  ): Promise<GithubInstallationAccessToken> {
+    const startedAt = Date.now();
+    try {
+      const token = await withTimeout(mint(), this.mintTimeoutMs);
+      recordInstallationTokenMint({outcome: 'success', durationMs: Date.now() - startedAt});
+      return token;
+    } catch (error) {
+      recordInstallationTokenMint({outcome: 'failure', durationMs: Date.now() - startedAt});
+      throw error;
+    }
+  }
+
+  private async readEnvelope(
+    workspaceId: string,
+    installationId: number,
+  ): Promise<InstallationTokenEnvelope | undefined> {
+    const raw = await this.options.secretStore.read(workspaceId, installationId);
+    if (raw === null) return undefined;
+
+    const envelope = parseInstallationTokenEnvelope(raw);
+    if (envelope === undefined) {
+      logger().warn({installationId}, 'github installation token cache envelope failed to decode');
+    }
+    return envelope;
+  }
+
+  private async writeEnvelope(
+    workspaceId: string,
+    installationId: number,
+    envelope: InstallationTokenEnvelope,
+  ): Promise<void> {
+    await this.options.secretStore.write(workspaceId, installationId, envelope);
+  }
+
+  private async resolveWorkspaceId(installationId: number): Promise<string> {
+    const nowMs = this.now().getTime();
+    const cached = this.workspaceIds.get(installationId);
+    if (cached && cached.expiresAtMs > nowMs) return cached.workspaceId;
+
+    const workspaceId = await this.options.resolveWorkspaceId(installationId);
+    this.workspaceIds.set(installationId, {
+      workspaceId,
+      expiresAtMs: nowMs + this.workspaceCacheTtlMs,
+    });
+    return workspaceId;
+  }
+}
+
+type ActiveBackoffEnvelope = InstallationTokenEnvelope & {
+  backoffUntil: Date;
+  backoffReason: NonNullable<InstallationTokenEnvelope['backoffReason']>;
+};
+
+type TokenEnvelope = InstallationTokenEnvelope & {token: string; expiresAt: Date};
+
+function activeBackoff(
+  envelope: InstallationTokenEnvelope | undefined,
+  now: Date,
+): envelope is ActiveBackoffEnvelope {
+  return (
+    backoffActive(envelope, now) &&
+    envelope?.backoffUntil !== undefined &&
+    envelope.backoffReason !== undefined
+  );
+}
+
+function canServeStale(
+  envelope: InstallationTokenEnvelope | undefined,
+  now: Date,
+): envelope is TokenEnvelope {
+  const terminalBackoff =
+    activeBackoff(envelope, now) && mintErrorClassForReason(envelope.backoffReason) === 'terminal';
+  return (
+    envelope?.token !== undefined &&
+    envelope.expiresAt !== undefined &&
+    stillValid(envelope.expiresAt, now) &&
+    !terminalBackoff
+  );
+}
+
+function tokenFromEnvelope(envelope: InstallationTokenEnvelope): GithubInstallationAccessToken {
+  if (!envelope.token || !envelope.expiresAt) {
+    throw new GithubIntegrationProviderError(
+      'malformed-provider-response',
+      'GitHub installation token cache envelope is missing a token or expiry',
+    );
+  }
+  return {
+    token: envelope.token,
+    expiresAt: envelope.expiresAt,
+    ...(envelope.permissions === undefined ? {} : {permissions: envelope.permissions}),
+  };
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<T>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        new GithubIntegrationProviderError(
+          'timeout',
+          'Timed out minting GitHub installation access token',
+        ),
+      );
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}

package/src/config.test.ts

@@ -0,0 +1,14 @@
+import {describe, expect, it} from '@shipfox/vitest/vi';
+import {normalizeGithubApiBaseUrl} from './config.js';
+
+describe('normalizeGithubApiBaseUrl', () => {
+  it.each([
+    ['https://api.github.com', 'https://api.github.com'],
+    ['https://api.github.com/', 'https://api.github.com'],
+    ['https://github.example.test/api/v3///', 'https://github.example.test/api/v3'],
+  ])('normalizes %s', (baseUrl, expected) => {
+    const result = normalizeGithubApiBaseUrl(baseUrl);
+
+    expect(result).toBe(expected);
+  });
+});

package/src/config.ts

@@ -0,0 +1,47 @@
+import {createConfig, str, url} from '@shipfox/config';
+
+const trailingSlashesPattern = /\/+$/u;
+
+export const config = createConfig({
+  GITHUB_APP_ID: str({
+    desc: "Numeric ID of the GitHub App, found on the app's settings page. Required.",
+  }),
+  GITHUB_APP_PRIVATE_KEY: str({
+    desc: 'Private key of the GitHub App in PEM format, used to sign API requests. Newlines may be written as \\n and are restored at runtime. Required.',
+  }),
+  GITHUB_APP_CLIENT_ID: str({
+    desc: 'OAuth client ID of the GitHub App, used for user sign-in. Required.',
+  }),
+  GITHUB_APP_CLIENT_SECRET: str({
+    desc: 'OAuth client secret of the GitHub App. Required.',
+  }),
+  GITHUB_APP_WEBHOOK_SECRET: str({
+    desc: 'Secret used to verify the signature of incoming GitHub webhooks. Must match the value set on the GitHub App. Required.',
+  }),
+  GITHUB_APP_SLUG: str({
+    desc: 'URL slug of the GitHub App, used to build install and callback links. Required.',
+  }),
+  GITHUB_APP_USERNAME: str({
+    desc: 'GitHub App username used as the Git commit author when checkout credentials are persisted. Set this to the app username, such as my-app. The [bot] suffix is added automatically. Leave unset to keep Git author identity unset.',
+    default: undefined,
+  }),
+  GITHUB_API_BASE_URL: url({
+    desc: 'Base URL used for GitHub REST API requests. Set this only for GitHub Enterprise Server or a compatible test server.',
+    default: 'https://api.github.com',
+  }),
+  GITHUB_INSTALL_STATE_SECRET: str({
+    desc: 'Secret used to sign the state token that protects the GitHub App install flow. Required.',
+  }),
+});
+
+export function normalizedGithubPrivateKey(): string {
+  return config.GITHUB_APP_PRIVATE_KEY.replaceAll('\\n', '\n');
+}
+
+export function normalizeGithubApiBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(trailingSlashesPattern, '');
+}
+
+export function normalizedGithubApiBaseUrl(): string {
+  return normalizeGithubApiBaseUrl(config.GITHUB_API_BASE_URL);
+}