GitHub App Scaffold

Stack (2026 Standard)

• Runtime: Node.js + TypeScript
• Framework: Probot
• Auth + App primitives:

  @octokit/app

• API client:

  @octokit/rest

  (via

  context.octokit

  )

• Probot gives webhook-first structure, fast.

• @octokit/app

  handles JWT + installation tokens clean.
• You can drop to raw Octokit when you need control.

Scaffold CLI

npx create-probot-app my-github-app
cd my-github-app
npm run dev

• Choose TypeScript.
• Choose a minimal template.
• Keep scope narrow. One automation loop per app if possible.

Workflow

1. Identify automation opportunities.
2. Map them to webhook events + repo actions.
3. Scaffold with Probot.
4. Implement webhook handlers.
5. Lock permissions to minimum viable.
6. Deploy.
7. Verify in a staging repo/org.

• What exact event starts the automation?
• What repo/issue/PR state is required?
• What GitHub writes will happen?
• What permissions are required for those writes?
• What is the failure mode? (retry, comment, label, noop)

Project Structure

my-github-app/
├─ src/
│  └─ index.ts          # App entry, register webhooks
├─ test/                # Probot tests (add early)
├─ app.yml              # App metadata + permissions (if used)
├─ package.json
└─ tsconfig.json

src/
├─ index.ts             # wire events only
├─ handlers/
│  ├─ pull-request.ts
│  ├─ issues.ts
│  └─ push.ts
├─ domain/
│  └─ <automation>.ts   # core decision logic, testable
└─ github/
   └─ client.ts         # small helpers around octokit

Common Use Cases

• Auto-label by paths changed.
• Enforce checklist comments.
• Auto-request reviewers.

• Triage labels by templates.
• Auto-close stale issues with escape hatches.
• Route issues to teams.

• Comment on risky diffs.
• Enforce conventions on PR open/sync.
• Block merge with a status check.

• Trigger external systems on PR/push.
• Mirror commit status back to GitHub.
• Manage deployments via checks.

Permissions Model

• Start from events + writes.
• Add only required read/write scopes.
• Prefer read-only unless you must write.

• Labeling issues/PRs → Issues: Read & Write, Pull requests: Read & Write
• Commenting → Issues or Pull requests: Read & Write
• Status checks → Commit statuses or Checks: Read & Write
• Repo config reads → Metadata: Read-only (always)

• Action
• API call
• Permission required

Deployment Options

• Vercel: fast for webhook handlers.
• Cloud functions: AWS Lambda, GCP Cloud Functions, Azure Functions.
• Self-hosted: long-lived workers, queues, custom infra.

• Probot can run serverless with light glue.
• For heavier automations, use queues and idempotency keys.
• Keep webhook latency low; defer heavy work.

Verification Steps

npm run dev

1. Create a GitHub App (dev) and install it on a staging repo.
2. Point the webhook URL to your dev tunnel.
3. Trigger the event (open PR, edit issue, push).
4. Confirm logs show the expected handler path.
5. Confirm the GitHub side effect happened (label, comment, check).
6. Run tests for decision logic + handlers.

• Event received.
• Guardrails applied (repo, org, branch filters).
• API calls succeed.
• No duplicate side effects.
• Permissions are sufficient but not excessive.

skills/github-app-scaffold/references/probot-patterns.md