Back to Details

github-app-scaffold

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub App Scaffold

GitHub App 脚手架

Turn existing GitHub automation into a real GitHub App with Probot and the modern Octokit stack.
借助Probot和现代化Octokit技术栈，将现有的GitHub自动化流程转化为标准的GitHub App。

Stack (2026 Standard)

技术栈（2026年标准）

  • 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.
  • 运行环境：Node.js + TypeScript
  • 框架：Probot
  • 认证与App基础组件：
    @octokit/app
  • API客户端：
    @octokit/rest
    （通过
    context.octokit
    调用）
选择该技术栈的原因：
  • Probot提供以Webhook为核心的快速开发架构。
  • @octokit/app
    可简洁处理JWT与安装令牌。
  • 当需要更精细控制时，可直接使用原生Octokit。

Scaffold CLI

脚手架CLI

Use Probot’s official scaffolder:
bash
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.
使用Probot官方脚手架工具：
bash
npx create-probot-app my-github-app
cd my-github-app
npm run dev
搭建过程中：
  • 选择TypeScript。
  • 选择极简模板。
  • 控制应用范围，尽可能每个App仅实现一个自动化流程。

Workflow

工作流程

Follow this sequence. Keep it tight.
  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.
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)
遵循以下步骤，确保流程紧凑高效。
  1. 识别可自动化的场景。
  2. 将场景映射为Webhook事件与仓库操作。
  3. 使用Probot搭建项目框架。
  4. 实现Webhook处理器。
  5. 配置最小必要权限。
  6. 部署应用。
  7. 在测试仓库/组织中验证功能。
自动化场景发现清单：
  • 触发自动化的具体事件是什么？
  • 需要满足仓库/议题/PR的何种状态？
  • 将在GitHub上执行哪些写入操作？
  • 这些写入操作需要哪些权限？
  • 失败处理方式是什么？（重试、添加评论、添加标签、无操作）

Project Structure

项目结构

Default Probot layout is already decent:
text
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:
text
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.
Probot默认项目结构已足够合理：
text
my-github-app/
├─ src/
│  └─ index.ts          # App入口，注册Webhook
├─ test/                # Probot测试用例（尽早添加）
├─ app.yml              # App元数据 + 权限配置（若使用）
├─ package.json
└─ tsconfig.json
当业务逻辑复杂后，建议采用以下内部结构：
text
src/
├─ index.ts             # 仅负责关联事件
├─ handlers/
│  ├─ pull-request.ts
│  ├─ issues.ts
│  └─ push.ts
├─ domain/
│  └─ <automation>.ts   # 核心决策逻辑，可测试
└─ github/
   └─ client.ts         # Octokit相关的小型辅助工具
原则：简化Webhook关联代码，将核心决策逻辑放在深层模块中。

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.
PR自动化：
  • 根据修改路径自动添加标签。
  • 强制要求清单式评论。
  • 自动请求评审人。
议题管理：
  • 根据模板自动分类议题标签。
  • 自动关闭长期未处理的议题，并提供例外机制。
  • 将议题分配至对应团队。
代码评审机器人：
  • 对高风险代码差异添加评论。
  • 在PR创建/同步时强制遵循代码规范。
  • 通过状态检查阻止不符合要求的合并。
CI集成：
  • 在PR创建/代码推送时触发外部系统。
  • 将提交状态同步回GitHub。
  • 通过检查机制管理部署流程。

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
将权限视为对外接口，尽可能缩小权限范围。
实施方法：
  • 从事件与写入操作出发。
  • 仅添加必要的读/写权限范围。
  • 除非必须执行写入操作，否则优先选择只读权限。
典型权限映射：
  • 为议题/PR添加标签 → 议题：读写权限，拉取请求：读写权限
  • 添加评论 → 议题或拉取请求：读写权限
  • 状态检查 → 提交状态或检查：读写权限
  • 读取仓库配置 → 元数据：只读权限（始终如此）
在仓库中维护一个简单的权限对照表：
  • 操作
  • API调用
  • 所需权限

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.
选择最适合Webhook模型的最简部署平台。
推荐默认选项：
  • Vercel：处理Webhook响应速度快。
  • 云函数：AWS Lambda、GCP Cloud Functions、Azure Functions。
  • 自托管：长期运行的工作进程、队列、自定义基础设施。
注意事项：
  • Probot可通过少量适配代码在无服务器环境运行。
  • 对于复杂的自动化任务，使用队列与幂等键。
  • 降低Webhook响应延迟，将繁重任务延迟处理。

Verification Steps

验证步骤

Do not skip this.
Local loop:
bash
npm run dev
Then:
  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.
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
.
请勿跳过此步骤。
本地验证流程：
bash
npm run dev
随后：
  1. 创建一个开发版GitHub App，并安装到测试仓库。
  2. 将Webhook URL指向本地开发隧道。
  3. 触发目标事件（创建PR、编辑议题、推送代码）。
  4. 确认日志中显示预期的处理器路径。
  5. 确认GitHub上产生了预期的副作用（添加标签、评论、状态检查）。
  6. 运行决策逻辑与处理器的测试用例。
基础验证清单：
  • 事件已接收。
  • 已应用防护规则（仓库、组织、分支过滤）。
  • API调用成功。
  • 无重复副作用。
  • 权限足够且不过度。
参考文档：
skills/github-app-scaffold/references/probot-patterns.md
。