GitHub App Scaffold

Turn existing GitHub automation into a real GitHub App with Probot and the modern Octokit stack.

Stack (2026 Standard)

• Runtime: Node.js + TypeScript

• Framework: Probot

• Auth + App primitives: @octokit/app

• API client: @octokit/rest (via context.octokit )

Why this stack:

• 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

Use Probot’s official scaffolder:

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

During setup:

• Choose TypeScript.

• Choose a minimal template.

• Keep scope narrow. One automation loop per app if possible.

Workflow

Follow this sequence. Keep it tight.

• Identify automation opportunities.

• Map them to webhook events + repo actions.

• Scaffold with Probot.

• Implement webhook handlers.

• Lock permissions to minimum viable.

• Deploy.

• Verify in a staging repo/org.

Automation discovery checklist:

• 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

Default Probot layout is already decent:

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

Suggested internal structure once logic grows:

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

Rule: keep webhook glue thin. Put decisions in deep modules.

Common Use Cases

PR automation:

• Auto-label by paths changed.

• Enforce checklist comments.

• Auto-request reviewers.

Issue management:

• Triage labels by templates.

• Auto-close stale issues with escape hatches.

• Route issues to teams.

Code review bots:

• Comment on risky diffs.

• Enforce conventions on PR open/sync.

• Block merge with a status check.

CI integration:

• Trigger external systems on PR/push.

• Mirror commit status back to GitHub.

• Manage deployments via checks.

Permissions Model

Treat permissions as an interface. Small surface.

Approach:

• Start from events + writes.

• Add only required read/write scopes.

• Prefer read-only unless you must write.

Typical mappings:

• 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)

Keep a simple table in the repo:

• Action

• API call

• Permission required

Deployment Options

Pick the simplest host that fits the webhook model.

Good defaults:

• Vercel: fast for webhook handlers.

• Cloud functions: AWS Lambda, GCP Cloud Functions, Azure Functions.

• Self-hosted: long-lived workers, queues, custom infra.

Notes:

• Probot can run serverless with light glue.

• For heavier automations, use queues and idempotency keys.

• Keep webhook latency low; defer heavy work.

Verification Steps

Do not skip this.

Local loop:

npm run dev

Then:

• Create a GitHub App (dev) and install it on a staging repo.

• Point the webhook URL to your dev tunnel.

• Trigger the event (open PR, edit issue, push).

• Confirm logs show the expected handler path.

• Confirm the GitHub side effect happened (label, comment, check).

• Run tests for decision logic + handlers.

Minimal verification checklist:

• Event received.

• Guardrails applied (repo, org, branch filters).

• API calls succeed.

• No duplicate side effects.

• Permissions are sufficient but not excessive.

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