@shipfox/api-integration-github 12.7.0 → 14.0.0

package/src/core/bot-identity.ts

@@ -0,0 +1,19 @@
+import {config} from '#config.js';
+
+const GITHUB_APP_BOT_SUFFIX = '[bot]';
+
+export function githubBotLogin(username: string): string {
+  const normalized = username.trim();
+  return normalized.toLowerCase().endsWith(GITHUB_APP_BOT_SUFFIX)
+    ? normalized
+    : `${normalized}${GITHUB_APP_BOT_SUFFIX}`;
+}
+
+export function configuredGithubAppBotLogin(): string | undefined {
+  const configuredUsername = config.GITHUB_APP_USERNAME?.trim();
+  return configuredUsername ? githubBotLogin(configuredUsername) : undefined;
+}
+
+export function githubAppBotLogin(): string {
+  return configuredGithubAppBotLogin() ?? githubBotLogin(config.GITHUB_APP_SLUG);
+}

package/src/core/install.test.ts

@@ -37,6 +37,9 @@ function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient
     fetchRepositoryFile: vi.fn(() => {
       throw new Error('not used');
     }),
+    listRepositoryCommits: vi.fn(() => {
+      throw new Error('not used');
+    }),
     createInstallationAccessToken: vi.fn(() =>
       Promise.resolve({
         token: 'ghs_installationtoken',

package/src/core/source-control.test.ts

@@ -8,6 +8,7 @@ const VALID_COMMIT = 'a'.repeat(40);
 function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient {
   return {
     exchangeOAuthCode: vi.fn(() => Promise.resolve('token')),
+    getBotUser: vi.fn(() => Promise.resolve({id: 12_345, login: 'shipfox-test[bot]'})),
     listUserInstallations: vi.fn(() => Promise.resolve({installationIds: [], nextCursor: null})),
     getInstallation: vi.fn(() => {
       throw new Error('not used');
@@ -56,6 +57,9 @@ function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient
         size: 58,
       }),
     ),
+    listRepositoryCommits: vi.fn(() =>
+      Promise.resolve([{sha: 'a'.repeat(40)}, {sha: 'b'.repeat(40)}]),
+    ),
     createInstallationAccessToken: vi.fn(() =>
       Promise.resolve({
         token: 'ghs_installationtoken',
@@ -258,6 +262,96 @@ describe('GithubSourceControlProvider', () => {
     });
   });
 
+  it('resolves a branch ref to the commit it points at', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/main',
+    });
+
+    expect(result).toEqual({ref: 'refs/heads/main', commit: VALID_COMMIT});
+    expect(github.listRepositoryCommits).toHaveBeenCalledWith({
+      installationId,
+      repositoryId: 42,
+      ref: 'refs/heads/main',
+    });
+  });
+
+  it('resolves a tag ref to the commit it points at', async () => {
+    await createInstallation();
+    const github = githubClient({
+      listRepositoryCommits: vi.fn(() => Promise.resolve([{sha: 'c'.repeat(40)}])),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/tags/v1.0.0',
+    });
+
+    expect(result).toEqual({ref: 'refs/tags/v1.0.0', commit: 'c'.repeat(40)});
+  });
+
+  it('maps a ref with no commits to ref-not-found', async () => {
+    await createInstallation();
+    const github = githubClient({
+      listRepositoryCommits: vi.fn(() => Promise.resolve([])),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/missing',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'ref-not-found'});
+  });
+
+  it('rejects a commit response with an invalid object id', async () => {
+    await createInstallation();
+    const github = githubClient({
+      listRepositoryCommits: vi.fn(() => Promise.resolve([{sha: 'not-a-commit'}])),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/main',
+    });
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+      message: 'GitHub ref "refs/heads/main" resolved to an invalid commit',
+    });
+  });
+
+  it.each([
+    'a'.repeat(40),
+    'refs/pull/17/head',
+    'main',
+    '-evil',
+  ])('rejects ref %s as ref-invalid', async (ref) => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref,
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'ref-invalid'});
+    expect(github.listRepositoryCommits).not.toHaveBeenCalled();
+  });
+
   it('fetches repository file contents using the provider-owned repository id', async () => {
     await createInstallation();
     const github = githubClient();
@@ -349,7 +443,7 @@ describe('GithubSourceControlProvider', () => {
       },
       gitAuthor: {
         name: 'shipfox-test[bot]',
-        email: '1+shipfox-test[bot]@users.noreply.github.com',
+        email: '12345+shipfox-test[bot]@users.noreply.github.com',
       },
     });
     expect(result.repositoryUrl).not.toContain('ghs_installationtoken');
@@ -358,6 +452,91 @@ describe('GithubSourceControlProvider', () => {
       repositoryId: 42,
       permissions: {contents: 'write'},
     });
+    expect(github.getBotUser).toHaveBeenCalledWith({
+      username: 'shipfox-test[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+  });
+
+  it('propagates bot identity resolution failures for write checkouts', async () => {
+    await createInstallation();
+    const github = githubClient({
+      getBotUser: vi.fn(() =>
+        Promise.reject(
+          new GithubIntegrationProviderError('provider-rejected', 'bot user not found'),
+        ),
+      ),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'provider-rejected'});
+  });
+
+  it('propagates unexpected bot lookup errors', async () => {
+    await createInstallation();
+    const github = githubClient({
+      getBotUser: vi.fn(() => Promise.reject(new Error('unexpected lookup failure'))),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    await expect(result).rejects.toThrow('unexpected lookup failure');
+  });
+
+  it('rejects write checkout when the bot identity resolver is unavailable', async () => {
+    await createInstallation();
+    const github = githubClient();
+    delete github.getBotUser;
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'provider-unavailable'});
+  });
+
+  it('omits the author and bot lookup for read-only checkouts', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'read'},
+    });
+
+    expect(result.gitAuthor).toBeUndefined();
+    expect(github.getBotUser).not.toHaveBeenCalled();
+  });
+
+  it('omits the author and bot lookup when the App username is unset', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github, () => undefined);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    expect(result.gitAuthor).toBeUndefined();
+    expect(github.getBotUser).not.toHaveBeenCalled();
   });
 
   it('defaults the checkout ref to the repository default branch', async () => {

package/src/core/source-control.ts

@@ -10,6 +10,7 @@ import {
   type IntegrationConnection,
   isRecord,
   isValidGitObjectId,
+  isValidResolvableRef,
   isValidTriggerRef,
   type ListFilesInput,
   type ListRepositoriesInput,
@@ -20,26 +21,30 @@ import {
   type RepositoryPage,
   type RepositorySnapshot,
   type RepositoryVisibility,
+  type ResolvedRef,
+  type ResolveRefInput,
   type ResolveRepositoryInput,
   type SourceControlProvider,
   type TriggerReference,
 } from '@shipfox/api-integration-spi';
 import type {GithubApiClient, GithubRepository} from '#api/client.js';
-import {config} from '#config.js';
 import {getGithubInstallationByConnectionId} from '#db/installations.js';
+import {configuredGithubAppBotLogin} from './bot-identity.js';
 import {GithubIntegrationProviderError} from './errors.js';
 
 type GithubIntegrationConnection = IntegrationConnection<'github'>;
 
 const GITHUB_PROVIDER = 'github';
-const GITHUB_APP_BOT_SUFFIX = '[bot]';
 const SEARCH_PAGE_SIZE = 100;
 const SEARCH_MAX_PAGES_PER_REQUEST = 5;
 
 export class GithubSourceControlProvider
   implements SourceControlProvider<GithubIntegrationConnection>
 {
-  constructor(private readonly github: GithubApiClient) {}
+  constructor(
+    private readonly github: GithubApiClient,
+    private readonly appBotLogin: () => string | undefined = configuredGithubAppBotLogin,
+  ) {}
 
   async listRepositories(
     input: ListRepositoriesInput<GithubIntegrationConnection>,
@@ -192,6 +197,37 @@ export class GithubSourceControlProvider
     };
   }
 
+  async resolveRef(input: ResolveRefInput<GithubIntegrationConnection>): Promise<ResolvedRef> {
+    if (!isValidResolvableRef(input.ref)) {
+      throw new GithubIntegrationProviderError(
+        'ref-invalid',
+        `GitHub ref ${formatRefForMessage(input.ref)} is not a resolvable branch or tag name`,
+      );
+    }
+    const installationId = await this.installationId(input.connection.id);
+    const {repositoryId} = parseGithubRepositoryLocator(input.externalRepositoryId);
+    const commits = await this.github.listRepositoryCommits({
+      installationId,
+      repositoryId,
+      ref: input.ref,
+    });
+    const commit = commits[0]?.sha;
+    if (!commit) {
+      throw new GithubIntegrationProviderError(
+        'ref-not-found',
+        `GitHub ref ${formatRefForMessage(input.ref)} does not resolve to a commit`,
+      );
+    }
+    if (!isValidGitObjectId(commit)) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        `GitHub ref ${formatRefForMessage(input.ref)} resolved to an invalid commit`,
+      );
+    }
+
+    return {ref: input.ref, commit};
+  }
+
   async createCheckoutSpec(
     input: CreateCheckoutSpecInput<GithubIntegrationConnection>,
   ): Promise<CheckoutSpec> {
@@ -204,7 +240,11 @@ export class GithubSourceControlProvider
       repositoryId,
       permissions: input.permissions,
     });
-    const gitAuthor = githubAppGitAuthor();
+    const botLogin = this.appBotLogin();
+    const gitAuthor =
+      botLogin && input.permissions?.contents === 'write'
+        ? await githubAppGitAuthor(this.github, token, botLogin)
+        : undefined;
 
     return {
       repositoryUrl: repository.cloneUrl,
@@ -250,13 +290,27 @@ function sameGithubRepository(
   return Boolean(firstName && secondName && firstName.toLowerCase() === secondName.toLowerCase());
 }
 
-function githubAppGitAuthor(): CheckoutSpec['gitAuthor'] {
-  const appUsername = config.GITHUB_APP_USERNAME?.trim();
-  if (!appUsername) return undefined;
-  const name = appUsername.endsWith(GITHUB_APP_BOT_SUFFIX)
-    ? appUsername
-    : `${appUsername}${GITHUB_APP_BOT_SUFFIX}`;
-  return {name, email: `${config.GITHUB_APP_ID}+${name}@users.noreply.github.com`};
+function formatRefForMessage(ref: string): string {
+  return JSON.stringify(ref);
+}
+
+async function githubAppGitAuthor(
+  github: GithubApiClient,
+  installationAccessToken: string,
+  name: string,
+): Promise<CheckoutSpec['gitAuthor']> {
+  if (!github.getBotUser) {
+    throw new GithubIntegrationProviderError(
+      'provider-unavailable',
+      'GitHub bot identity resolution is unavailable',
+    );
+  }
+
+  const botUser = await github.getBotUser({username: name, installationAccessToken});
+  return {
+    name: botUser.login,
+    email: `${botUser.id}+${botUser.login}@users.noreply.github.com`,
+  };
 }
 
 function toRepositorySnapshot(repository: GithubRepository): RepositorySnapshot {

package/src/index.test.ts

@@ -1,3 +1,4 @@
+import {githubEventCatalog} from '@shipfox/api-integration-github-dto';
 import {githubInstallationTokenNamespace} from '#api/installation-token-envelope.js';
 import {createGithubIntegrationProvider} from '#index.js';
 
@@ -19,7 +20,7 @@ vi.mock('#core/webhook-processor.js', () => ({
 describe('createGithubIntegrationProvider', () => {
   it('shares installation-token cleanup with the direct and composed processors', async () => {
     const deleteSecrets = vi.fn(() => Promise.resolve(1));
-    createGithubIntegrationProvider({
+    const provider = createGithubIntegrationProvider({
       github: {} as never,
       getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
       connectGithubInstallation: vi.fn() as never,
@@ -31,6 +32,7 @@ describe('createGithubIntegrationProvider', () => {
       getIntegrationConnectionById: vi.fn(() => Promise.resolve(undefined)),
       deleteSecrets,
     });
+    expect(provider.eventCatalog).toBe(githubEventCatalog);
     const processorOptions = state.processorOptions as {
       deleteInstallationTokenSecret: (params: {
         workspaceId: string;

package/src/index.ts

@@ -1,3 +1,4 @@
+import {githubEventCatalog} from '@shipfox/api-integration-github-dto';
 import type {
   GetIntegrationConnectionByIdFn,
   PublishIntegrationEventReceivedFn,
@@ -102,6 +103,7 @@ export function createGithubIntegrationProvider(options: CreateGithubIntegration
   return {
     provider: 'github' as const,
     displayName: 'GitHub',
+    eventCatalog: githubEventCatalog,
     adapters: {
       source_control: new GithubSourceControlProvider(github),
       agent_tools: new GithubAgentToolsProvider({

package/src/presentation/routes/install.test.ts

@@ -61,6 +61,9 @@ function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient
     fetchRepositoryFile: vi.fn(() => {
       throw new Error('not used');
     }),
+    listRepositoryCommits: vi.fn(() => {
+      throw new Error('not used');
+    }),
     createInstallationAccessToken: vi.fn(() =>
       Promise.resolve({
         token: 'ghs_installationtoken',