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:<path> 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 driftgatefile validate shadcn-labs/pdfcn --file contribution-gates.json
# Print a README snippet for humansgatefile 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: gateson:  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 installnpm test        # tsx --test, offline, 35 testsnpm 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 (<tool> 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.