gatefile

gatefile

将隐藏的贡献门槛提取到机器可读的文件中。

每个仓库都藏着对外部贡献者的真实规则：开始前先评论、等待分配、提交时签署 DCO、获得担保、签署 CLA。如今，你往往要等 PR 被自动关闭后才会发现这些规则。gatefile 从仓库自己的文档中提取这些规则，生成 contribution-gates.json，这是一种机器可读的格式，可供工具（如 Greenlight）和 CI 使用。

问题

贡献者选中一个 issue，编写代码，提交 PR，然后机器人将其关闭：“你尚未被分配”“未获担保的作者会被自动关闭 PR”“缺少 Signed-off-by”。这些规则一直都写在 CONTRIBUTING.md 里，埋在一大段文字中，而且每个仓库都不一样。维护者一遍遍重复同样的纠正；贡献者一遍遍浪费同样的晚上。

gatefile 的作用

1. 提取：读取 CONTRIBUTING.md、PR 和 issue 模板、DCO/CLA 工作流文件、lefthook 钩子以及 CLA 文件（通过 GitHub API 或本地目录），并输出发现的门槛，每项都附有实际引用的原文作为依据。
2. 验证：将已提交的 contribution-gates.json 与最新提取结果进行比较，并报告差异（STALE、MISSING、SEVERITY_CHANGED）。存在差异时退出代码为 1，CI 可据此强制执行。
3. 徽章：生成 README 片段，用通俗易懂的语言告诉大家这些门槛。

contribution-gates.json 格式

{
  "version": 1,
  "repo": "shadcn-labs/pdfcn",
  "generatedFrom": ["CONTRIBUTING.md"],
  "gates": [
    {
      "id": "claim_first",
      "kind": "claim_first",
      "severity": "blocker",
      "evidence": "Comment before starting work, and check the thread first in case someone else is already working on it.",
      "source": "CONTRIBUTING.md"
    }
  ],
  "conventions": {
    "branchNaming": "Name your branch feat/block-name",
    "prTitleFormat": "PR titles should follow Conventional Commits",
    "requiredChecks": []
  }
}

门槛类型

kind	severity	含义
claim_first	blocker	开始工作前先在 issue 中评论
assignment_required	blocker	等待分配后再提交 PR
discuss_first	blocker	编码前先发起讨论或创建 issue
issue_first	blocker	每个 PR 都必须关联一个 issue
vouch_required	blocker	必须由现有成员为你担保
collaborators_only	blocker	只有仓库协作者可以提交 PR
no_direct_prs	blocker	不接受直接提交的 PR
dco_required	warn	提交需要带有 Signed-off-by 尾注（DCO）
cla_required	warn	必须签署贡献者许可协议

严重性：blocker 门槛可能导致 PR 在审核前被关闭或拒绝。warn 门槛可在 PR 提交后补齐。依据始终是源文件中的真实引文，截取至约 140 个字符，不会凭空编造。

使用 Docker 运行

gatefile 也提供 GHCR 上的容器镜像：ghcr.io/cloudcorprecords/gatefile。

将其用作 stdio MCP 服务：

docker run -i ghcr.io/cloudcorprecords/gatefile

可以在镜像名称后传入任意 CLI 命令，以替代默认的 mcp 参数：

docker run ghcr.io/cloudcorprecords/gatefile <command> [args]

用法

CLI

# Extract gates from a repo (GitHub API, GITHUB_TOKEN optional)
gatefile extract shadcn-labs/pdfcn

# Extract from a local clone instead (fully offline)
gatefile extract local --local ./pdfcn --out contribution-gates.json

# Validate the committed file against fresh docs, exit 1 on drift
gatefile validate shadcn-labs/pdfcn --file contribution-gates.json

# Print a README snippet for humans
gatefile badge shadcn-labs/pdfcn

MCP 服务

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "gatefile": {
      "command": "node",
      "args": ["/path/to/gatefile/dist/mcp.js"]
    }
  }
}

工具：

tool	inputs	返回内容
extract_gates	repo 或 localPath	完整的 contribution-gates.json 对象
validate_gates	recorded、repo 或 localPath	{ ok, drift[] }
gates_badge	repo 或 localPath	README Markdown 片段

CI 示例

在 GitHub Actions 工作流中确保门槛文件准确无误：

name: gates
on:
  pull_request:
    paths: ["CONTRIBUTING.md", ".github/**", "contribution-gates.json"]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx -y gatefile extract ${{ github.repository }} --out /tmp/fresh.json
      - run: npx -y gatefile validate ${{ github.repository }} --file contribution-gates.json

开发

npm install
npm test        # tsx --test, offline, 23 tests
npm run build   # tsc to dist/
npm run dev -- extract owner/repo --json

TypeScript ESM，Node 20+，使用 zod 定义模式，使用原生 fetch 调用 GitHub API。测试使用 test/fixtures/ 中基于有文档记录的案例构建的真实场景样例（开始前评论并要求 DCO 和 issue 优先；先分配；仅需担保；宽松）。

许可证

MIT，Rene Turcios 2026。

工具套件

此工具是开源贡献工作流中的四款工具之一，它们都以 @reneturcios npm 作用域发布，且每款都提供 CLI 和 MCP 服务（<tool> mcp）：

1. gatefile（npx @reneturcios/gatefile）会提取仓库的贡献门槛，并将其写入已提交的 contribution-gates.json。
2. greenlight（npx @reneturcios/greenlight）会预检问题（GO / RISKY / TAKEN / GATED / STALE），在 check 和 scan 中使用 gatefile 的输出，然后认领问题、做好准备并提交 PR。
3. claimcheck（npx @reneturcios/claimcheck）会监控过期认领，以及停留在 fork 上的修复。
4. prwatch（npx @reneturcios/prwatch）会根据哪些未合并 PR 需要你立即处理，对它们进行分类。