feat(github): restrict app installation tokens to selected repositories

[robingenz]

Adds an optional repositories field to GitHubAppAuth, so a GitHub App installation access token can be restricted to specific repositories instead of everything the installation can reach.

github({
  auth: {
    appId,
    privateKey,
    owner: "capawesome-team",
    repositories: ["repo-sdk"],
  },
});

Behaviour

• When repositories is set, the access-token request (POST /app/installations/{id}/access_tokens) is sent with the JSON body { "repositories": [...] } — the GitHub REST repositories parameter, repository names without the owner.
• When omitted, the request is sent with no body exactly as before, so the default behaviour is unchanged. Non-breaking.
• The option is fixed at construction time and the token cache is per token-source instance, so no cache-key change was needed (noted in a code comment where the token is minted).
• No permissions or repository_ids support — only the repository-name restriction.

Motivation: least-privilege tokens for CI consumers that hand the token to build steps.

Tests

Two cases added to test/providers/github-app.test.ts, mirroring the existing GitHub App token tests:

• the mint request body contains exactly the configured repositories, and the resulting token is the one used for the subsequent repo call
• no request body (and no Content-Type) when repositories is omitted

Docs

• docs/authentication/github.mdx — new repositories row in the GitHub App auth TypeTable plus a short "Restricting the token to specific repositories" section
• skills/repo-sdk-auth/SKILL.md — one bullet under the GitHub App specifics

[Copilot]

🟢 Approval recommended

The change is opt-in, preserves the prior default request behavior, and is covered by targeted unit tests plus corresponding documentation updates.

Pull request overview

Adds an opt-in least-privilege mode for GitHub App installation tokens by allowing callers to restrict minted installation access tokens to a configured set of repository names, while preserving the previous “no request body” behavior by default.

Changes:

• Extended GitHubAppAuth/AppTokenSourceOptions with optional repositories?: string[] and threaded it through provider construction.
• Updated GitHub App token minting to conditionally include a JSON body { repositories: [...] } (and Content-Type) only when configured.
• Added unit tests and documentation covering both the restricted-token and default no-body behaviors.

File summaries

File	Description
test/providers/github-app.test.ts	Adds test coverage for restricted token mint requests and unchanged default behavior (no body / no Content-Type).
src/providers/github/index.ts	Exposes repositories?: string[] on GitHubAppAuth and passes it into the app token source.
src/providers/github/app-auth.ts	Implements conditional JSON request body + Content-Type when minting installation tokens with repository restrictions.
skills/repo-sdk-auth/SKILL.md	Documents the new optional repositories auth option for GitHub App usage.
docs/authentication/github.mdx	Documents repositories in the auth type table and adds a usage section with example.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Deploy preview available at: https://f9ad125f.repo-sdk-page.pages.dev.

Built with commit 7f4be0a.