内容
gh-baselineCI](https://github.com/wrxck/gh-baseline/actions/workflows/ci.yml/badge.svg)](https://github.com/wrxck/gh-baseline/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@matthesketh/gh-baseline)
[
[](https://nodejs.org/)
> 配置驱动、幂等、安全优先的 GitHub 账户强化行界面、交互式终端用户界面和 MCP 服务器。
`eline` 将 GitHub中的每个仓库提升到一致的标准（分支保护、安全功能、社区文件、CI 工作流、徽章、标签），并保持不变。它为 GitHub 执行与 [`fleet`](https://github.com/wrxck/fleet) 为 Docker 应用或 Cloudflare 账户强化 MCP 所做的工作相同。
它有三种运行方式：
- **命令行界面** — 用于 cron、脚本、自动化。程序化和确定性：相同的输入，相同的输出。
- **交互式终端用户界面** （基于 Ink 用于需要人工组合的部分：构建新配置文件、分类应用哪些违规、深入扫描结果。
- **MCP 服务器** — 用于 Claude Code。MCP 接口纯粹是程序化的，**故意比原始 Octokit 更窄**：LLM 永远不会获得账户的密钥。
## 设计原则：在确定性部分程序化，在非确定性部分交互
`gh-baseline` 的大部分工作是确定性的：给定配置文件和仓库，差异、应用、审计日志条目都是输入的函数。这些操作存在于命令行界面和 MCP 中，永远不需要人工干预。
终端用户界面（TUI）用于真正创造性的部分：
- 构建新配置文件（`gh-baseline profiles new`）
- 编辑现有配置文件（`gh-baseline profiles edit <name>`）
- 深入多仓库扫描并选择要修复的违规（`gh-baseline scan --interactive`）
- 从精心维护的仓库中逆向工程配置文件（`gh-baseline profiles reverse <repo>`）
TUI 的输出始终是 YAML/TS 配置文件，可以提交到配置文件仓库。之后，每次后续运行都是程序化的：`gh-baseline apply <profile> <repo>` 的行为与从终端、cron 作业或 MCP 工具调用时相同。
## 为什么存在
典型的 GitHub 账户会积累数十个仓库，每个仓库都有自己的漂移：不一致的分支保护、缺少的 `SECURITY.md`、没有 Dependabot、过时的标签、没有 CI、未测试的工作流、没有徽章的 README。手动修复这些问题很繁琐，而且工作会在创建新仓库时立即失效。
`gh-baseline` 将**目标状态**定义为配置文件（YAML/TS 规范），扫描每个仓库以检查它，并幂等地应用缺失的部分。重新运行始终是安全的。
## 安全模型
MCP 公开的操作分为多个层级；LLM 只会与安全的操作交互。
| 层级 | 内容 | LLM 访问 | 命令行界面访问 |
|------|------|-----------|------------|
| **1 — 只读** | 扫描、审计、差异、列表、医生 | 是 | 是 |
| **2 — 幂等添加** | 应用标准标签、添加 `SECURITY.md`、启用 Dependabot、设置仓库描述/主题 | 是（默认 `dryRun=true`） |使用 `--apply` 持久化） |
| **3 — 修改变更** | 替换分支保护规则、修改社区更改合并设置 | 通过 MCP 仅限差异 | 是（使用 `--apply |
| **4坏性 / 不可逆** | 删除、存转移、更改可见性、强制推送 | **从不** 在 MCP 中 | 仅限命令行界面 `--yes-i-am-sure` |
级的保护措施：
- **允许列表** — `~/.config/gh-baseline/config.json` 声明哪些仓库和组织是可触及的。默认拒绝。通配符需要 `unsafe_allow_all`。
- **审计日志** — 每次追加到 `~/.-baseline/audit`，包含时间戳、工具、仓库、参数、结果和 `dryRun` 标志。
- **速率 — Octokit 限流 + 每分钟每个工具，以阻止失控的循环。
- **PR 而非推送** — 文件更改始终通过 PR 进入默认分支；从不直接推送到主分支。
- **幂等性** — 每个 `apply_*` 操作都是 `read → diff → no-op-if-empty → minimal change`。重新运行是安全的。
- **严格的 zod 模式** — 每个 MCP 工具参数都经过验证；`assertRepoSlug`、`assertBranchName` 等。
- **令牌范围检查** — 启动时，服务器检查 PAT 的范围不足（错误）或范围过多（警告），则拒绝运行。
## 安装
```bash
npm install -g @matthesketh/gh-baseline
gh-baseline init # 交互式：身份验证 + 允许列表 + 初始配置文件
gh-baseline doctor # 验证身份验证、范围、配置
```
## 用法
```bash
# 扫描一个仓库与最严格的捆绑配置文件
gh-baseline scan owner/repo --profile oss-public
# 扫描所有允许的仓库，摘要表格
gh-baseline scan --all
# 显示当前分支保护与配置文件之间的差异
gh-baseline apply branch-protection owner/repo --profile oss-public
# 实际应用（没有 `--apply` 是干燥运行）
gh-baseline apply branch-protection owner/repo --profile oss-public --apply 检查已应用的内容
gh-baseline audit --tail 50
# 列出捆绑的配置文件
gh-baseline profiles list
gh-baseline profiles show oss-public
```
## MCP 用法
添加到您的 Claude Code MCP 设置：
```json
{
"mcpServers": {
"gh-baseline": {
"command": "gh-baseline",
"args": ["mcp"]
}
}
}
```
然后在 Claude Code 中：
> "扫描我的所有 Node 库与 `library` 配置文件，并告诉我哪些库缺少分支保护。"
## 配置文件
配置文件是声明式的 — 它们说明仓库**应该**是什么样子，而不是如何实现。
`0.1.0` 中捆绑：
- `oss-public` — 最严格的，用于公共 OSS 项目（所有保护措施都开启）。
- `library` *(路线图)* — 可发布的 npm/library 标准。
- `application` *(路线图)* — 内部可部署的应用标准。
- `personal` *(路线图)* — 为临时仓库放松的标准。
自定义配置文件是 TS 文件，从 `src/profiles/` 导出（或在 MVP 后，`~/.config/gh-baseline/profiles/` 中的 YAML）。
## 路线图（冰山）
`0.1.0` 是基础：扫描 + 分支保护应用 + 安全主干。分层在单独的版本中 — 每个新功能都经过相同的层级分类、默认干燥运行和审计处理。
### 仓库卫生
- 通过 PR 应用社区文件（`CONTRIBUTING.md`、`CODE_OF_CONDUCT.md`、`SECURITY.md`、PR/问题模板）
- README 徽章（CI、许可证、npm、覆盖率、OSSF Scorecard）幂等地注入
- `CODEOWNERS`、`.editorconfig`、`FUNDING.yml`
- 标准标签集（`bug`、`enhancement`、`good first issue`、`security`、`breaking`）
- `CHANGELOG.md` 脚手架（release-please）
### CI/CD
- 测试工作流应用（每个配置文件的 Node 矩阵）
- CodeQL 设置
- Dependabot 版本 + 安全更新
- 工作流 SHA-fix 强制执行
- Dependabot 补丁/次要 PR 的自动合并
### 安全态势
- Dependabot 警报 + 安全更新 + 推送保护
- 机密扫描 + 自定义模式
- 私有漏洞报告
- 所需签名提交（每个配置文件）
- 组织范围的 2FA 强制执行
### 分支和合并策略
- 配置文件驱动的分支保护规则
- 自动删除已合并的分支
- 线性历史
- `CODEOWNERS` 驱动的所需审查者
- 所需 PR 会话解析
### 账户 / 组织级别
- 配置文件 README 设置，固定仓库管理
- 组织设置审计（成员权限、第三方访问）
- 外部协作者审计
- 组织机密 / 变量审计（仅名称 — 永远不检查值）
- Webhook 审计
### 跨切报告
- OSSF Scorecard 运行 + 增量跟踪
- 配置文件合规性报告
- 漂移报告（自上次 `apply` 后漂移的仓库）
- 过时问题 / PR 分类
- 聚合依赖项报告
### 批量 + 生命周期
- 批量将配置文件应用于 N 个仓库，每个仓库确认
仓库自动上线钩子
- 带有宽限期的存档过时仓库
- 跨组织转移（仅限命令行界面，多次确认）
- 逆向工程：从现有的精心维护的仓库中提取配置文件规范
### 集成 *(后期，功能标志后面)*
- 线性 / Jira / Notion 同步问题分类
/ TelegramMessage 警报 从 `docs夹同步 Wiki 内容
## 开发
```bash
git clone https://github.com/wrxck/gh-bas
cd gh-basnpm install
npm test
npm run build
```
代码库镜像 [`fleet
