GitHub capabilities require an app-installation connection.

Error message

GitHub capabilities require an app-installation connection.

What it means

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.

Source

Thrown at mastracode/factory/src/integrations/github/integration.ts:1480

function reviewEventToGithub(event: Exclude<InputOf<'createReview'>['event'], undefined>) {
  if (event === 'approve') return 'APPROVE' as const;
  if (event === 'request-changes') return 'REQUEST_CHANGES' as const;
  return 'COMMENT' as const;
}

function requirePullRequestNumber(value: string): number {
  return requirePositiveId(value, 'pull request');
}

function requirePositiveId(value: string, resource: string): number {
  const parsed = parsePositiveInteger(value);
  if (parsed === null) throw new Error(`GitHub ${resource} id must be a positive integer.`);
  return parsed;
}

function getGithubInstallationId(connection: IntegrationConnection): number {
  if (connection.type !== 'app-installation') {
    throw new Error('GitHub capabilities require an app-installation connection.');
  }
  return connection.installationId;
}

function getSingleSourceId(sourceIds: string[], message: string): string {
  if (sourceIds.length !== 1) throw new Error(message);
  return sourceIds[0]!;
}

function normalizeLabels(labels: string[] | undefined): string[] {
  return [...new Set((labels ?? []).map(label => label.trim()).filter(Boolean))];
}

function requireSourceId(sourceId: string | undefined, message: string): string {
  if (!sourceId) throw new Error(message);
  return sourceId;
}

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const conn = { type: 'pat', token } as IntegrationConnection;
const gh = new GithubIntegration(conn); // capabilities throw
// after
const conn = { type: 'app-installation', installationId: 12345 } as IntegrationConnection;

Defensive patterns

Strategy: validation

Validate before calling

if (connection.type !== 'app-installation') throw new Error(`GitHub App installation required, connection is: ${connection.type}`);

Type guard

function isAppInstallation(c: IntegrationConnection): c is IntegrationConnection & { type: 'app-installation'; installationId: number } {
  return c.type === 'app-installation';
}

Try / catch

try {
  const gh = githubCapabilityFor(connection);
} catch (e) {
  if ((e as Error).message.includes('app-installation')) {
    return promptUserToInstallGithubApp();
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/2ee6a31c48b03b37. Report an issue: GitHub.