Gatefile

gatefile

Hidden contribution gates, extracted into a file machines can read.

Every repo hides its real rules for outside contributors: comment before you start, wait to be assigned, sign off your commits, get vouched, sign a CLA. Today you discover those rules by getting your PR auto-closed. gatefile extracts them from the repo's own docs into contribution-gates.json, a machine-readable format that tools (like Greenlight) and CI can consume.

The problem

A contributor picks an issue, writes the code, opens the PR, and a bot closes it: "you were not assigned", "unvouched authors are auto-closed", "missing Signed-off-by". The rules were always in CONTRIBUTING.md, buried in prose, different on every repo. Maintainers repeat the same corrections; contributors waste the same evenings.

What gatefile does

1. extract: reads CONTRIBUTING.md, PR and issue templates, DCO/CLA workflow files, lefthook hooks, and CLA files (from the GitHub API or a local directory) and emits the gates it finds, each with a real quoted line as evidence. In API mode, a repo with no CONTRIBUTING file or no PR template of its own also inherits the organization level default from the org's .github repository, exactly the fallback GitHub itself applies; inherited files are labelled owner/.github: in generatedFrom and as the gate source, and a repo file always wins over the org default for its group.
2. validate: compares a committed contribution-gates.json against a fresh extraction and reports drift (STALE, MISSING, SEVERITY_CHANGED). Exit code 1 on drift, so CI can enforce it.
3. badge: renders a README snippet that tells humans the gates in plain language.

The contribution-gates.json format

{

"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": [] } }

Gate kinds

Severity: blocker gates can get a PR closed or rejected before review. warn gates can be fixed after the PR opens. Evidence is always a real quote from the source file, trimmed to about 140 characters, never invented.

Run it with Docker

gatefile also ships as a container image on GHCR: ghcr.io/cloudcorprecords/gatefile.

Use it as a stdio MCP server:

docker run -i ghcr.io/cloudcorprecords/gatefile

Any CLI command can be passed after the image name instead of the default mcp argument:

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

Usage

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 server

Add to your MCP client config:

{

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

Tools:

CI example

Keep the gates file honest in a GitHub Actions workflow:

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

Development

npm install

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

TypeScript ESM, Node 20+, zod for schemas, native fetch for the GitHub API. Tests use real-world fixtures in test/fixtures/ modeled on documented cases (comment-before-starting plus DCO plus issue-first; assignment-first; vouch-only; permissive).

License

MIT, Rene Turcios 2026.

The toolkit

This tool is one of four in a lifecycle for open-source contribution work, all published under the @reneturcios npm scope and each available as a CLI and an MCP server ( mcp):

1. gatefile (npx @reneturcios/gatefile) extracts a repo's contribution gates into a committed contribution-gates.json.
2. greenlight (npx @reneturcios/greenlight) pre-flights issues (GO / RISKY / TAKEN / GATED / STALE), consumes gatefile's output in check and scan, then claims, preps, and opens PRs.
3. claimcheck (npx @reneturcios/claimcheck) watches for stale claims and fixes parked on forks.
4. prwatch (npx @reneturcios/prwatch) triages your open PRs by what needs you right now.