{"record":{"id":"2ee6a31c48b03b37","repo":"mastra-ai/mastra","slug":"github-capabilities-require-an-app-installation-co","errorCode":null,"errorMessage":"GitHub capabilities require an app-installation connection.","messagePattern":"GitHub capabilities require an app-installation connection\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/integrations/github/integration.ts","lineNumber":1480,"sourceCode":"function reviewEventToGithub(event: Exclude<InputOf<'createReview'>['event'], undefined>) {\n  if (event === 'approve') return 'APPROVE' as const;\n  if (event === 'request-changes') return 'REQUEST_CHANGES' as const;\n  return 'COMMENT' as const;\n}\n\nfunction requirePullRequestNumber(value: string): number {\n  return requirePositiveId(value, 'pull request');\n}\n\nfunction requirePositiveId(value: string, resource: string): number {\n  const parsed = parsePositiveInteger(value);\n  if (parsed === null) throw new Error(`GitHub ${resource} id must be a positive integer.`);\n  return parsed;\n}\n\nfunction getGithubInstallationId(connection: IntegrationConnection): number {\n  if (connection.type !== 'app-installation') {\n    throw new Error('GitHub capabilities require an app-installation connection.');\n  }\n  return connection.installationId;\n}\n\nfunction getSingleSourceId(sourceIds: string[], message: string): string {\n  if (sourceIds.length !== 1) throw new Error(message);\n  return sourceIds[0]!;\n}\n\nfunction normalizeLabels(labels: string[] | undefined): string[] {\n  return [...new Set((labels ?? []).map(label => label.trim()).filter(Boolean))];\n}\n\nfunction requireSourceId(sourceId: string | undefined, message: string): string {\n  if (!sourceId) throw new Error(message);\n  return sourceId;\n}\n","sourceCodeStart":1462,"sourceCodeEnd":1498,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/integrations/github/integration.ts#L1462-L1498","documentation":"getGithubInstallationId only accepts IntegrationConnection objects of type 'app-installation'; GitHub App capabilities need the installation id to mint installation tokens. A connection of any other type (e.g. a PAT or OAuth connection) cannot provide an installation id, so the helper throws.","triggerScenarios":"Invoking GitHub capabilities (PR reads, triage comments, reviews) with a project connected via a personal access token or OAuth user token instead of a GitHub App installation.","commonSituations":"Team connected GitHub with a classic PAT; OAuth app connection used where a GitHub App is required; connection type changed by an admin without re-syncing.","solutions":["Install the GitHub App on the target repositories and connect via 'app-installation' type.","Check connection.type before calling GitHub capability methods.","Migrate the project's integration from PAT/OAuth to a GitHub App installation.","Verify the installation id is present on the connection object after install."],"exampleFix":"// before\nconst conn = { type: 'pat', token } as IntegrationConnection;\nconst gh = new GithubIntegration(conn); // capabilities throw\n// after\nconst conn = { type: 'app-installation', installationId: 12345 } as IntegrationConnection;","handlingStrategy":"validation","validationCode":"if (connection.type !== 'app-installation') throw new Error(`GitHub App installation required, connection is: ${connection.type}`);","typeGuard":"function isAppInstallation(c: IntegrationConnection): c is IntegrationConnection & { type: 'app-installation'; installationId: number } {\n  return c.type === 'app-installation';\n}","tryCatchPattern":"try {\n  const gh = githubCapabilityFor(connection);\n} catch (e) {\n  if ((e as Error).message.includes('app-installation')) {\n    return promptUserToInstallGithubApp();\n  }\n  throw e;\n}","preventionTips":["Use GitHub App installations (not PATs) for all GitHub integrations.","Check connection.type in UI before exposing GitHub-only features.","Document that OAuth/PAT connections don't unlock capability methods."],"tags":["github","authentication","configuration"],"backgroundTag":"wrong-auth-connection-type","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}