caretta-github-app-installer

Register a GitHub App for caretta's code-review bot via the GitHub App Manifest Flow.

Run it from any repository — it spins up a local Bun server, opens your browser to GitHub's app-registration form, exchanges the returned code for credentials, and writes them where caretta expects.

Usage

bunx caretta-github-app-installer

For an organization-owned app:

GITHUB_ORG=my-org APP_NAME=my-caretta-bot bunx caretta-github-app-installer

Environment variables

| Variable | Default | Purpose | | ------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- | | PORT | 3000 | Port for the local callback server. | | GITHUB_ORG | (personal) | Register the app under this organization. | | APP_NAME | caretta-dev-bot | Default name for the new app (editable on GitHub). | | WEBHOOK_URL | https://example.com/caretta-webhook | Webhook target embedded in the manifest. GitHub requires a public URL even with active=false. |

What it writes

• ~/.config/caretta/dev-ui-bot.pem — the app's private key, chmod 600.
• ./.env.github-app in the current directory — DEV_BOT_APP_ID, DEV_BOT_PRIVATE_KEY, etc.

After the flow completes:

1. Install the app on a repo via the URL printed in the terminal.
2. Copy the installation ID from the resulting URL into DEV_BOT_INSTALLATION_ID in .env.github-app.
3. source .env.github-app && caretta.

Programmatic use

import { run } from "caretta-github-app-installer";

await run({
  port: 4000,
  owner: "my-org",
  appName: "my-bot",
});

Lower-level building blocks are exported from the package root: buildManifest, createHandler, convertCode, writeAppCredentials, formatEnvFile, defaultConfigPaths, githubNewAppUrl.

Development

bun install
bun test
bun run typecheck
bun src/cli.ts   # run locally

Built on Bun; the published bin requires bun (use bunx, not npx).