@shipfox/api-integration-github 12.3.0 → 12.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-github",
   "license": "MIT",
-  "version": "12.3.0",
+  "version": "12.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -28,7 +28,7 @@
     "octokit": "^5.0.3",
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-integration-spi": "1.1.0",
+    "@shipfox/api-integration-spi": "1.1.1",
     "@shipfox/api-integration-github-dto": "12.2.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.5",

package/src/api/client.test.ts

@@ -1,9 +1,25 @@
 import {GithubIntegrationProviderError} from '#core/errors.js';
-import {createGithubApiClient} from './client.js';
+import {
+  GITHUB_STATEFUL_INSTALLATION_TOKEN,
+  GITHUB_STATELESS_INSTALLATION_TOKEN,
+} from '#test/index.js';
+import {createGithubApiClient, mapGithubError} from './client.js';
 
-const {createInstallationAccessTokenMock} = vi.hoisted(() => ({
-  createInstallationAccessTokenMock: vi.fn(),
-}));
+const GITHUB_INSTALLATION_TOKEN_PATTERN = /^ghs_[A-Za-z0-9._-]{36,}$/u;
+
+const {createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => {
+  class RequestErrorMock extends Error {
+    constructor(
+      message: string,
+      public readonly status: number,
+    ) {
+      super(message);
+      this.name = 'HttpError';
+    }
+  }
+
+  return {createInstallationAccessTokenMock: vi.fn(), RequestErrorMock};
+});
 
 vi.mock('octokit', () => ({
   App: class App {
@@ -12,13 +28,42 @@ vi.mock('octokit', () => ({
     };
   },
   Octokit: {
+    plugin() {
+      return this;
+    },
     defaults(options: unknown) {
       return {defaults: options};
     },
   },
-  RequestError: class RequestError extends Error {},
+  RequestError: RequestErrorMock,
 }));
 
+describe('mapGithubError', () => {
+  it.each([400, 409, 422])('maps HTTP %i to a terminal provider rejection', async (status) => {
+    const error = new RequestErrorMock(`GitHub rejected request with HTTP ${status}`, status);
+
+    const result = mapGithubError(() => Promise.reject(error));
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: `GitHub rejected request with HTTP ${status}`,
+      status,
+    });
+  });
+
+  it('preserves the status when mapping provider unavailability', async () => {
+    const error = new RequestErrorMock('GitHub is unavailable', 503);
+
+    const result = mapGithubError(() => Promise.reject(error));
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'provider-unavailable',
+      message: 'GitHub is unavailable',
+      status: 503,
+    });
+  });
+});
+
 describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
   beforeEach(() => {
     createInstallationAccessTokenMock.mockReset();
@@ -26,7 +71,10 @@ describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
 
   it('mints a repository-scoped, read-only installation token', async () => {
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const client = createGithubApiClient();
 
@@ -36,9 +84,11 @@ describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
     });
 
     expect(result).toEqual({
-      token: 'ghs_installationtoken',
+      token: GITHUB_STATELESS_INSTALLATION_TOKEN,
       expiresAt: new Date('2026-06-10T12:00:00.000Z'),
     });
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN).toMatch(GITHUB_INSTALLATION_TOKEN_PATTERN);
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN.slice(4).split('.')).toHaveLength(3);
     expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
       installation_id: 1,
       repository_ids: [42],
@@ -46,18 +96,24 @@ describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
     });
   });
 
-  it('mints a repository-scoped write installation token when requested', async () => {
+  it('passes through a stateful repository-scoped write token', async () => {
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const client = createGithubApiClient();
 
-    await client.createInstallationAccessToken({
+    const result = await client.createInstallationAccessToken({
       installationId: 1,
       repositoryId: 42,
       permissions: {contents: 'write'},
     });
 
+    expect(result.token).toBe(GITHUB_STATEFUL_INSTALLATION_TOKEN);
+    expect(GITHUB_STATEFUL_INSTALLATION_TOKEN).toMatch(GITHUB_INSTALLATION_TOKEN_PATTERN);
+    expect(GITHUB_STATEFUL_INSTALLATION_TOKEN).not.toContain('.');
     expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
       installation_id: 1,
       repository_ids: [42],

package/src/api/client.ts

@@ -4,6 +4,11 @@ import ky, {HTTPError, TimeoutError} from 'ky';
 import {App, Octokit, RequestError} from 'octokit';
 import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#config.js';
 import {GithubIntegrationProviderError} from '#core/errors.js';
+import {recordInstallationTokenFormat} from '#metrics/index.js';
+import {
+  getGithubInstallationOctokit,
+  githubInstallationTokenFormatPlugin,
+} from './github-octokit.js';
 
 const NEXT_PAGE_RE = /[?&]page=(\d+)/;
 const TRAILING_SLASHES_RE = /\/+$/;
@@ -186,7 +191,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     limit: number;
     cursor?: string | undefined;
   }): Promise<GithubRepositoryPage> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const page = cursorToPage(input.cursor);
     const response = await mapGithubError(() =>
       octokit.rest.apps.listReposAccessibleToInstallation({
@@ -205,7 +212,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     installationId: number;
     repositoryId: number;
   }): Promise<GithubRepository> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const response = await mapGithubError(() =>
       octokit.request('GET /repositories/{repository_id}', {
         repository_id: input.repositoryId,
@@ -223,7 +232,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     limit: number;
     cursor?: string | undefined;
   }): Promise<GithubFilePage> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const repository = await this.getRepository({
       installationId: input.installationId,
       repositoryId: input.repositoryId,
@@ -303,7 +314,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     ref: string;
     path: string;
   }): Promise<GithubFileContent> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const repository = await this.getRepository({
       installationId: input.installationId,
       repositoryId: input.repositoryId,
@@ -363,6 +376,8 @@ class OctokitGithubApiClient implements GithubApiClient {
       );
     }
 
+    recordInstallationTokenFormat(response.data.token);
+
     const expiresAt = new Date(response.data.expires_at);
     if (Number.isNaN(expiresAt.getTime())) {
       throw new GithubIntegrationProviderError(
@@ -383,7 +398,9 @@ class OctokitGithubApiClient implements GithubApiClient {
       this.app = new App({
         appId: config.GITHUB_APP_ID,
         privateKey: normalizedGithubPrivateKey(),
-        Octokit: Octokit.defaults({baseUrl: normalizedGithubApiBaseUrl()}),
+        Octokit: Octokit.plugin(githubInstallationTokenFormatPlugin).defaults({
+          baseUrl: normalizedGithubApiBaseUrl(),
+        }),
       });
     }
     return this.app;
@@ -433,13 +450,19 @@ export async function mapGithubError<T>(
     if (error instanceof GithubIntegrationProviderError) throw error;
     if (error instanceof RequestError) {
       if (error.status === 404) {
-        throw new GithubIntegrationProviderError(notFoundReason, error.message);
+        throw new GithubIntegrationProviderError(
+          notFoundReason,
+          error.message,
+          undefined,
+          error.status,
+        );
       }
       if (error.status === 429 || isGithubRateLimitError(error)) {
         throw new GithubIntegrationProviderError(
           'rate-limited',
           error.message,
           retryAfterSeconds(error),
+          error.status,
         );
       }
       if (error.status === 401 || error.status === 403) {
@@ -447,10 +470,24 @@ export async function mapGithubError<T>(
           'access-denied',
           error.message,
           retryAfterSeconds(error),
+          error.status,
         );
       }
       if (error.status >= 500) {
-        throw new GithubIntegrationProviderError('provider-unavailable', error.message);
+        throw new GithubIntegrationProviderError(
+          'provider-unavailable',
+          error.message,
+          undefined,
+          error.status,
+        );
+      }
+      if (error.status >= 400) {
+        throw new GithubIntegrationProviderError(
+          'provider-rejected',
+          error.message,
+          undefined,
+          error.status,
+        );
       }
     }
     if (error instanceof Error && error.name === 'AbortError') {

package/src/api/github-octokit.test.ts

@@ -0,0 +1,115 @@
+import {generateKeyPairSync} from 'node:crypto';
+import {once} from 'node:events';
+import {createServer} from 'node:http';
+import {App, Octokit} from 'octokit';
+import {
+  GITHUB_STATEFUL_INSTALLATION_TOKEN,
+  GITHUB_STATELESS_INSTALLATION_TOKEN,
+} from '#test/index.js';
+import {
+  createGithubInstallationTokenFormatPlugin,
+  getGithubInstallationOctokit,
+} from './github-octokit.js';
+
+const {privateKey} = generateKeyPairSync('rsa', {
+  modulusLength: 2048,
+  publicKeyEncoding: {type: 'spki', format: 'pem'},
+  privateKeyEncoding: {type: 'pkcs8', format: 'pem'},
+});
+const BEARER_AUTHORIZATION = /^bearer /iu;
+
+describe('GitHub installation Octokit', () => {
+  it.each([
+    {
+      format: 'stateless',
+      token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+      override: 'enabled' as const,
+      authorization: `bearer ${GITHUB_STATELESS_INSTALLATION_TOKEN}`,
+    },
+    {
+      format: 'stateful',
+      token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+      override: 'disabled' as const,
+      authorization: `token ${GITHUB_STATEFUL_INSTALLATION_TOKEN}`,
+    },
+    {
+      format: 'stateful without an override',
+      token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+      override: undefined,
+      authorization: `token ${GITHUB_STATEFUL_INSTALLATION_TOKEN}`,
+    },
+  ])('requests and authenticates with a $format token', async ({
+    token,
+    override,
+    authorization,
+  }) => {
+    const calls: Array<{
+      method: string | undefined;
+      path: string | undefined;
+      authorization: string | undefined;
+      tokenFormatOverride: string | undefined;
+    }> = [];
+    const server = createServer((request, response) => {
+      calls.push({
+        method: request.method,
+        path: request.url,
+        authorization: request.headers.authorization,
+        tokenFormatOverride: request.headers['x-github-stateless-s2s-token'] as string | undefined,
+      });
+
+      if (request.method === 'POST' && request.url === '/app/installations/123/access_tokens') {
+        response.writeHead(201, {'content-type': 'application/json'}).end(
+          JSON.stringify({
+            token,
+            expires_at: '2099-01-01T00:00:00.000Z',
+            permissions: {metadata: 'read'},
+            repository_selection: 'all',
+          }),
+        );
+        return;
+      }
+
+      if (request.method === 'GET' && request.url === '/installation/repositories') {
+        response
+          .writeHead(200, {'content-type': 'application/json'})
+          .end(JSON.stringify({total_count: 0, repositories: []}));
+        return;
+      }
+
+      response.writeHead(404, {'content-type': 'application/json'}).end('{"message":"Not Found"}');
+    });
+    server.listen({host: '127.0.0.1', port: 0});
+    await once(server, 'listening');
+    const address = server.address();
+    if (!address || typeof address === 'string') throw new Error('Expected TCP server address.');
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+
+    try {
+      const InstallationTokenOctokit = Octokit.plugin(
+        createGithubInstallationTokenFormatPlugin(override),
+      ).defaults({baseUrl});
+      const app = new App({appId: 1, privateKey, Octokit: InstallationTokenOctokit});
+      const octokit = await getGithubInstallationOctokit(app, 123, baseUrl);
+
+      await octokit.rest.apps.listReposAccessibleToInstallation();
+
+      expect(calls).toEqual([
+        {
+          method: 'POST',
+          path: '/app/installations/123/access_tokens',
+          authorization: expect.stringMatching(BEARER_AUTHORIZATION),
+          tokenFormatOverride: override,
+        },
+        {
+          method: 'GET',
+          path: '/installation/repositories',
+          authorization,
+          tokenFormatOverride: undefined,
+        },
+      ]);
+    } finally {
+      server.close();
+      await once(server, 'close');
+    }
+  });
+});

package/src/api/github-octokit.ts

@@ -0,0 +1,49 @@
+import {type App, Octokit} from 'octokit';
+import {config, normalizedGithubApiBaseUrl} from '#config.js';
+import {GithubIntegrationProviderError} from '#core/errors.js';
+import {recordInstallationTokenFormat} from '#metrics/index.js';
+
+const INSTALLATION_TOKEN_REQUEST_PATH = /\/app\/installations\/[^/]+\/access_tokens(?:\?|$)/u;
+type GithubInstallationTokenFormatOverride = 'enabled' | 'disabled' | undefined;
+
+export function createGithubInstallationTokenFormatPlugin(
+  override: GithubInstallationTokenFormatOverride,
+): Parameters<typeof Octokit.plugin>[0] {
+  return (octokit) => {
+    octokit.hook.before('request', (options) => {
+      if (
+        !override ||
+        options.method !== 'POST' ||
+        !INSTALLATION_TOKEN_REQUEST_PATH.test(options.url)
+      ) {
+        return;
+      }
+
+      options.headers['x-github-stateless-s2s-token'] = override;
+    });
+  };
+}
+
+export const githubInstallationTokenFormatPlugin: Parameters<typeof Octokit.plugin>[0] =
+  createGithubInstallationTokenFormatPlugin(config.GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE);
+
+export async function getGithubInstallationOctokit(
+  app: App,
+  installationId: number,
+  baseUrl = normalizedGithubApiBaseUrl(),
+): Promise<Octokit> {
+  const authentication = (await app.octokit.auth({
+    type: 'installation',
+    installationId,
+  })) as {token?: unknown};
+
+  if (typeof authentication.token !== 'string') {
+    throw new GithubIntegrationProviderError(
+      'malformed-provider-response',
+      'GitHub installation authentication did not include a token',
+    );
+  }
+
+  recordInstallationTokenFormat(authentication.token);
+  return new Octokit({auth: authentication.token, baseUrl});
+}

package/src/api/installation-token-envelope.ts

@@ -19,15 +19,21 @@ const providerErrorReasons = [
   'rate-limited',
   'timeout',
   'provider-unavailable',
+  'provider-rejected',
   'malformed-provider-response',
   'content-too-large',
   'too-many-files',
 ] as const satisfies readonly IntegrationProviderErrorReason[];
 
 const providerErrorReasonSchema = z.enum(providerErrorReasons);
+const backoffErrorSchema = z.object({
+  message: z.string(),
+  status: z.number().int().optional(),
+});
 const terminalMintErrorReasons = new Set<IntegrationProviderErrorReason>([
   'access-denied',
   'installation-not-found',
+  'provider-rejected',
   'malformed-provider-response',
 ]);
 
@@ -44,6 +50,7 @@ const installationTokenEnvelopeSchema = z.object({
   permissions: z.record(z.string(), z.enum(['read', 'write', 'admin'])).optional(),
   backoffUntil: z.string().datetime().optional(),
   backoffReason: providerErrorReasonSchema.optional(),
+  backoffError: backoffErrorSchema.optional(),
 });
 
 export interface InstallationTokenEnvelope {
@@ -52,6 +59,12 @@ export interface InstallationTokenEnvelope {
   permissions?: Record<string, 'read' | 'write' | 'admin'> | undefined;
   backoffUntil?: Date | undefined;
   backoffReason?: IntegrationProviderErrorReason | undefined;
+  backoffError?:
+    | {
+        message: string;
+        status?: number | undefined;
+      }
+    | undefined;
 }
 
 export type MintErrorClass = 'transient' | 'terminal';
@@ -75,6 +88,7 @@ export function encodeInstallationTokenEnvelope(envelope: InstallationTokenEnvel
       backoffUntil: envelope.backoffUntil.toISOString(),
     }),
     ...(envelope.backoffReason !== undefined && {backoffReason: envelope.backoffReason}),
+    ...(envelope.backoffError !== undefined && {backoffError: envelope.backoffError}),
   });
 }
 
@@ -95,6 +109,7 @@ export function parseInstallationTokenEnvelope(raw: string): InstallationTokenEn
     permissions: result.data.permissions,
     backoffUntil: result.data.backoffUntil ? new Date(result.data.backoffUntil) : undefined,
     backoffReason: result.data.backoffReason,
+    backoffError: result.data.backoffError,
   };
 }
 
@@ -151,18 +166,25 @@ export function backoffMs(classified: ClassifiedMintError): number {
 export function providerErrorFromBackoff(
   reason: IntegrationProviderErrorReason,
   retryAfterMs: number,
+  backoffError?: InstallationTokenEnvelope['backoffError'],
 ): GithubIntegrationProviderError {
   return new GithubIntegrationProviderError(
     reason,
-    `GitHub installation token mint is backed off after ${reason}`,
+    backoffError?.message ?? `GitHub installation token mint is backed off after ${reason}`,
     Math.max(1, Math.ceil(retryAfterMs / 1000)),
+    backoffError?.status,
   );
 }
 
 export function toProviderError(error: unknown): GithubIntegrationProviderError {
   if (error instanceof GithubIntegrationProviderError) return error;
   if (error instanceof IntegrationProviderError) {
-    return new GithubIntegrationProviderError(error.reason, error.message, error.retryAfterSeconds);
+    return new GithubIntegrationProviderError(
+      error.reason,
+      error.message,
+      error.retryAfterSeconds,
+      error.status,
+    );
   }
   return new GithubIntegrationProviderError(
     'provider-unavailable',

package/src/api/installation-token-provider.test.ts

@@ -1,9 +1,15 @@
 import type {GetIntegrationConnectionByIdFn} from '@shipfox/api-integration-spi';
 import {GithubIntegrationProviderError} from '#core/errors.js';
-import {githubInstallationFactory} from '#test/index.js';
+import {
+  GITHUB_STATEFUL_INSTALLATION_TOKEN,
+  GITHUB_STATELESS_INSTALLATION_TOKEN,
+  githubInstallationFactory,
+} from '#test/index.js';
 import {encodeInstallationTokenEnvelope} from './installation-token-envelope.js';
 import {createGithubInstallationTokenProvider} from './installation-token-provider.js';
 
+const GITHUB_INSTALLATION_TOKEN_PATTERN = /^ghs_[A-Za-z0-9._-]{36,}$/u;
+
 const {appOptions, createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => ({
   appOptions: [] as unknown[],
   createInstallationAccessTokenMock: vi.fn(),
@@ -28,6 +34,9 @@ vi.mock('octokit', () => ({
     }
   },
   Octokit: {
+    plugin() {
+      return this;
+    },
     defaults(options: unknown) {
       return {defaults: options};
     },
@@ -47,26 +56,49 @@ describe('GithubInstallationTokenProvider', () => {
 
   it('mints a broad installation token on a cache miss', async () => {
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const provider = createGithubInstallationTokenProvider();
 
     const result = await provider.getInstallationAccessToken(1);
 
     expect(result).toEqual({
-      token: 'ghs_installationtoken',
+      token: GITHUB_STATELESS_INSTALLATION_TOKEN,
       expiresAt: new Date('2026-06-10T12:00:00.000Z'),
     });
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN).toMatch(GITHUB_INSTALLATION_TOKEN_PATTERN);
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN.slice(4).split('.')).toHaveLength(3);
     expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
       installation_id: 1,
     });
   });
 
+  it('passes through a stateful broad installation token', async () => {
+    createInstallationAccessTokenMock.mockResolvedValue({
+      data: {
+        token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    const result = await provider.getInstallationAccessToken(1);
+
+    expect(result.token).toBe(GITHUB_STATEFUL_INSTALLATION_TOKEN);
+    expect(GITHUB_STATEFUL_INSTALLATION_TOKEN).not.toContain('.');
+  });
+
   it('returns a cached token without a second mint', async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date('2026-06-10T11:00:00.000Z'));
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const provider = createGithubInstallationTokenProvider();
 
@@ -151,7 +183,10 @@ describe('GithubInstallationTokenProvider', () => {
         updatedAt: new Date(),
       });
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const provider = createGithubInstallationTokenProvider({
       getIntegrationConnectionById,
@@ -174,6 +209,10 @@ describe('GithubInstallationTokenProvider', () => {
     const second = await provider.getInstallationAccessToken(installationId);
 
     expect(first).toEqual(second);
+    expect(first.token).toBe(GITHUB_STATELESS_INSTALLATION_TOKEN);
+    expect(values.get(`${workspaceId}:${installationId}`)).toContain(
+      GITHUB_STATELESS_INSTALLATION_TOKEN,
+    );
     expect(lockCalls).toBe(1);
     expect(createInstallationAccessTokenMock).toHaveBeenCalledTimes(1);
   });

package/src/api/installation-token-provider.ts

@@ -4,8 +4,9 @@ import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#c
 import {GithubIntegrationProviderError} from '#core/errors.js';
 import {withInstallationTokenLock} from '#db/installation-token-lock.js';
 import {getGithubInstallationByInstallationId} from '#db/installations.js';
-import {recordInstallationTokenLookup} from '#metrics/index.js';
+import {recordInstallationTokenFormat, recordInstallationTokenLookup} from '#metrics/index.js';
 import {type GithubInstallationAccessToken, mapGithubError} from './client.js';
+import {githubInstallationTokenFormatPlugin} from './github-octokit.js';
 import {
   githubInstallationTokenNamespace,
   TOKEN_REFRESH_MARGIN_MS,
@@ -66,6 +67,8 @@ class OctokitGithubInstallationTokenProvider implements GithubInstallationTokenP
       );
     }
 
+    recordInstallationTokenFormat(response.data.token);
+
     const expiresAt = new Date(response.data.expires_at);
     if (Number.isNaN(expiresAt.getTime())) {
       throw new GithubIntegrationProviderError(
@@ -86,7 +89,7 @@ class OctokitGithubInstallationTokenProvider implements GithubInstallationTokenP
       this.app = new App({
         appId: config.GITHUB_APP_ID,
         privateKey: normalizedGithubPrivateKey(),
-        Octokit: Octokit.defaults({
+        Octokit: Octokit.plugin(githubInstallationTokenFormatPlugin).defaults({
           baseUrl: normalizedGithubApiBaseUrl(),
           throttle: {
             onRateLimit: (

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

@@ -190,6 +190,34 @@ describe('SharedInstallationTokenCache', () => {
     expect(mint).toHaveBeenCalledTimes(1);
   });
 
+  it('preserves terminal provider rejection details through backoff', async () => {
+    const store = createStore();
+    const mint = vi
+      .fn()
+      .mockRejectedValue(
+        new GithubIntegrationProviderError(
+          'provider-rejected',
+          'commit_id is missing',
+          undefined,
+          422,
+        ),
+      );
+    const shared = cache({store});
+
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'commit_id is missing',
+      status: 422,
+    });
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'commit_id is missing',
+      status: 422,
+    });
+
+    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'));