feat: add github app support

[kasin-it]

Summary by CodeRabbit

Release Notes

• New Features

  • Added GitHub App authentication support as an alternative to Personal Access Tokens
  • Made commit author/email configuration optional; bot identity auto-derives when not provided

• Documentation

  • Added comprehensive GitHub App setup guide with step-by-step instructions
  • Updated environment configuration documentation to reflect new authentication method

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ba855dc6-a81f-4b9f-bb9f-691286f1efc2

📥 Commits

Reviewing files that changed from the base of the PR and between 7612bf2 and 9489704.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (17)

• .env.example
• README.md
• SETUP.md
• docs/GITHUB-APP-SETUP.md
• env.test.ts
• env.ts
• package.json
• src/adapters/vcs/github.test.ts
• src/adapters/vcs/github.ts
• src/lib/create-vcs.ts
• src/lib/github-auth.test.ts
• src/lib/github-auth.ts
• src/sandbox/manager.test.ts
• src/sandbox/manager.ts
• src/sandbox/poll-agent.test.ts
• src/sandbox/poll-agent.ts
• src/workflows/agent.ts

---

📝 Walkthrough

Walkthrough

Replace GitHub personal access token authentication with GitHub App credentials across configuration, adapters, and sandbox provisioning. Add lazy token resolution, auto-derive bot commit identity, and introduce GitHub App setup documentation.

Changes

GitHub App Authentication Migration

Layer / File(s)	Summary
GitHub App Auth Library src/lib/github-auth.ts, src/lib/github-auth.test.ts	New module exports GitHubAppAuth interface and three functions: buildOctokit() constructs authenticated Octokit clients with automatic token refresh, mintInstallationToken() explicitly mints fresh installation tokens, and getBotIdentity() derives bot name/email from app metadata. Full test coverage validates each function and error paths.
Environment Schema & VCS Config Types env.ts, env.test.ts	Replace GITHUB_TOKEN schema with GitHub App credentials (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_INSTALLATION_ID); make COMMIT_AUTHOR/COMMIT_EMAIL optional with cross-field validation. Refactor VcsConfig from interface to discriminated union: GitHub carries auth: GitHubAppAuth, GitLab carries token: string. Add getVcsToken() exported function for lazy token resolution.
VCS Adapters & Factory src/adapters/vcs/github.ts, src/adapters/vcs/github.test.ts, src/lib/create-vcs.ts	Update GitHubConfig to use auth: GitHubAppAuth instead of token; initialize Octokit via buildOctokit(config.auth). Mock github-auth.js in adapter tests instead of @octokit/rest. Add type guard in createVCS() factory to enforce discriminated union validation before adapter construction.
Sandbox Config & Provisioning src/sandbox/manager.ts, src/sandbox/manager.test.ts	Replace direct token field in SandboxConfig with async getToken() resolver. Add buildCloneUrl() helper and refactor buildVcsUrls() to accept explicit token parameter. Update SandboxManager.provision() to call getToken() at provisioning time and pass token separately to URL builders. Update tests to use async token providers.
Poll Agent & Push Flow src/sandbox/poll-agent.ts, src/sandbox/poll-agent.test.ts	pushFromSandbox() and fixAndRetryPush() now obtain VCS config, mint fresh tokens via getVcsToken(), and rebuild URLs with both config and token. Define typed TestVcsConfig discriminated union in tests; mock getVcsToken() for conditional GitHub/GitLab token resolution.
Workflow Integration src/workflows/agent.ts	Resolve commit identity by checking explicit env overrides, deriving from GitHub App bot identity via getBotIdentity() for GitHub, or falling back to static defaults. Pass lazy token provider to SandboxManager and resolved identity values instead of static token/env values.
Configuration & Documentation .env.example, README.md, SETUP.md, docs/GITHUB-APP-SETUP.md, package.json	Replace GITHUB_TOKEN with GitHub App credentials in env template; make commit identity overrides commented/optional. Add comprehensive setup guide for GitHub App registration, installation, private-key encoding, and key rotation. Update README to document auto-derivation from bot identity. Add @octokit/auth-app dependency.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Blazity/ai-workflow#49: Modifies VCS configuration types and sandbox/poll-agent wiring in parallel.
• Blazity/ai-workflow#63: Changes environment schema validation in env.ts and related test fixtures.
• Blazity/ai-workflow#43: Updates SandboxManager.provision signature and token/URL provisioning behavior.

Poem

🐰 From tokens old to apps so new,
The workflow finds credentials true—
Installation IDs dance and gleam,
As PEM keys mint tokens in a stream.
Our rabbit hops through GitHub's door,
With scoped auth singing evermore! 🔐

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}