PatchGate

PatchGate is a deterministic GitHub pull-request readiness check. It answers one narrow question:

Does this pull request contain the policy, evidence, ownership, and human approval signals that this repository requires before a maintainer reviews it?

PatchGate is not a code-quality oracle, an AI-authorship detector, or a merge decision-maker. It produces a receipt that explains what passed, what is missing, and which human decision remains.

Why it exists

Coding agents make it easy to open a pull request before the repository's contribution contract has been understood. Maintainers then spend review time chasing missing issue links, unrecorded tests, unclear ownership, or an absent human gate.

PatchGate turns those expectations into an explicit, versioned policy and a repeatable preflight. The evaluator is local and deterministic; the GitHub adapter is an explicit boundary with a documented permission model.

Try one real pull request in five minutes

Add this temporary workflow to a test repository, open or update one pull request, and read the non-blocking PatchGate check. It does not change merge eligibility.

name: PatchGate shadow check

on:
  pull_request_target:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: read
  checks: read

jobs:
  patchgate:
    runs-on: ubuntu-latest
    steps:
      - uses: daichunghy/patchgate@34d998bbd59fa09dd9081e24f22abe812f97fbab
        with:
          fail-on: never
          create-check-run: true

Remove the workflow after the trial, or follow the shadow installation runbook before requesting any broader use.

Current status

Status (2026-09-06): public pre-release, 1 GitHub star, 0 forks, and no verified external users, downstream repositories, or pilots. The npm package is @daichunghy/patchgate@0.1.0-beta.5 (prerelease, dist-tag beta; the unscoped patchgate name belongs to a different project). The current Action release is v0.1.0-beta.5, and consumers should pin the immutable commit shown on that release page for shadow evaluation only. This is not production, not a v0.1 claim, and not evidence of external adoption.

Try it locally

The fastest path runs against the repository's recorded fixture and needs no token, network access, or pull-request checkout:

git clone https://github.com/daichunghy/patchgate.git
cd patchgate
npm ci
npm run verify
node dist/src/cli.js evaluate --event fixtures/pr-ready.json --report /tmp/patchgate-receipt.json

To inspect the result:

validate accepts --base as an alias of --policy. evaluate writes receipts with --report (or --output, the shared write-path alias); github snapshot and support-bundle write files with --output only. Giving evaluate both flags with different paths exits 2 (REPORT_OUTPUT_CONFLICT). --fail-on defaults to blocked, matching the Action.

Longer walkthrough: Getting started. The Case Lab contains ready, blocked, missing-evidence, human-gate, and policy-ambiguity scenarios that can be replayed from the fixture manifest with npm run case-lab.

node dist/src/cli.js explain /tmp/patchgate-receipt.json

For a first-use walkthrough, see docs/first-use.md. To use the CLI against a local repository:

node dist/src/cli.js preflight --base main --repo /path/to/repository
node dist/src/cli.js doctor --base /path/to/repository

Run npm run verify after making a change. It covers type checking, builds, deterministic fixtures, security cases, clean-room installation, and CLI smoke tests.

What it checks

A policy can require signals such as:

• an issue or discussion link;
• recorded, allowlisted test evidence;
• CODEOWNERS or sensitive-path ownership;
• commit-bound status checks;
• a declared human review gate;
• repository and workflow permissions that stay within the policy.

Every result is classified explicitly: ready, blocked, needs human review, evidence missing, or policy ambiguous. Discovery findings are advisory and cannot become enforcement by themselves.

GitHub Action

The repository contains a GitHub Action candidate for non-blocking shadow evaluation. Follow the Action usage guide before installing it in another repository.

The tagged pre-release v0.1.0-beta.5 is the current release; pin 34d998bbd59fa09dd9081e24f22abe812f97fbab for shadow evaluation. Production consumers must still wait for a stable public release. Do not use the placeholder patchgate/patchgate@v0.1.0-dev as an installable public reference.

For this checkout, the source-of-truth workflow is .github/workflows/patchgate-shadow.yml. It uses pull_request_target, checks out the trusted base revision, builds the Action bundle from that base, runs with fail-on: never, and updates one check run. A consented non-blocking shadow pilot may use an explicitly approved full-SHA pre-release commit by following the G4 shadow-installation runbook.

The trusted metadata lane uses pull_request_target only to read base-revision policy and authenticated metadata. It never checks out or executes pull-request code. Code that must run belongs in an unprivileged pull_request workflow. Pin an immutable commit when testing the Action, and keep the check non-blocking until a maintainer has reviewed the receipt and configured the repository rule that should honor it.

Security model

PatchGate separates three concerns:

1. The trusted metadata lane reads policy, GitHub metadata, rulesets, CODEOWNERS, reviews, and commit-bound checks from a trusted base revision.
2. The untrusted verification lane may run contributor code in a separate, read-only workflow with no repository secrets.
3. The decision lane evaluates normalized evidence and emits a receipt.

See the architecture, threat model, and GitHub permission contract before enabling a live adapter.

Contributing

Start with CONTRIBUTING.md, then choose a bounded issue:

• clean consumer-repository fixture;
• CODEOWNERS conformance fixtures;
• pilot request.

A useful contribution includes a reproducible fixture, the expected receipt, tests, and a short explanation of the boundary it exercises. Please open an issue first for changes that alter policy semantics or the security model.

For a consented maintainer walkthrough, use the shadow-pilot brief. External pilots are non-blocking, require maintainer consent, and should report both useful findings and false positives.

Documentation map

• Getting started
• Architecture
• Receipt contract
• Threat model
• GitHub adapter contract
• Action usage
• Implementation roadmap
• Security policy
• Support
• Changelog

Boundaries

PatchGate does not claim that code is correct, that a person reviewed code, that a receipt is tamper-proof, or that a repository is compliant with a standard. A status check can block a merge only after a repository maintainer explicitly configures the corresponding branch rule or ruleset.

The project is public pre-release software. Adoption means a separate maintainer-consented result in a real repository; local fixtures, source releases, and internal checks are not counted as external use.

License

Apache-2.0. See LICENSE.