Catch risky AI-generated PRs before merge — without checking out PR code.
Agent Gate is a GitHub Action that checks deterministic merge evidence: out-of-scope edits, GitHub Actions permission escalation, agent instruction drift, MCP config drift, and missing test-file evidence.
The Action uses no checkout of PR code, no runtime LLM calls, no repository script execution, and no policy loaded from an untrusted PR head. The same analyzer also powers local replay fixtures for deterministic demos.
Install in 10 minutes · See a real report · Why deterministic?
No AI PR gets merged without proof.
Agent Gate is pre-release. v0.2.2 is available as a GitHub prerelease and GitHub Marketplace Action. The core analyzer, CLI replay, root GitHub Action, PR comments, self-dogfooding workflow, and CI are implemented. APIs and rule names may change in later releases.
For released installs, prefer @v0.2.2 or a pinned commit SHA. @main tracks ongoing development.
See docs/v0.1.0-release-notes.md, docs/release-verification-v0.1.0.md, docs/release-verification-v0.1.1.md, docs/release-verification-v0.1.2.md, docs/release-verification-v0.1.3.md, docs/release-verification-v0.1.4.md, docs/release-verification-v0.1.5.md, docs/release-verification-v0.1.6.md, docs/release-verification-v0.2.0.md, docs/release-verification-v0.2.1.md, and docs/release-verification-v0.2.2.md for release notes and verification.
Latest external install smoke evidence is recorded for @v0.2.1 in docs/external-install-smoke-v0.2.1.md.
See docs/repository-governance.md for recommended branch protection and release safety settings.
See docs/evidence-model.md for stable finding IDs, re-derivable evidence, and warn-to-block planning.
See docs/launch-announcement-draft.md for a reusable launch announcement draft.
Feedback on AI-generated PR safety policies is welcome in #27.
An AI PR changed a GitHub Actions workflow and increased merge risk. In warn mode, Agent Gate keeps the check non-blocking while making the human decision obvious:
Agent Gate: NEEDS HUMAN DECISION
Decision: warn
Why: .github/workflows/release.yml changed outside the allowed contract scope.
Recommended next step: review the workflow change before merging.
Policy status: warning today; eligible to become a merge gate after tuning.
Finding ID: agf_...
- Out-of-contract edits: agent PRs changing files outside their declared scope.
- Workflow permission escalation: Actions workflows gaining broader write access.
- Agent control-plane drift (
agent-control-plane/drift): instruction or tool config changes that affect future agents. - Missing test evidence: high-risk source changes without matching test file changes.
- MCP config drift:
.mcp.jsonchanges that alter which tools agents can call.
LLM reviewers help with judgment. Agent Gate verifies deterministic merge evidence.
Agent Gate does not try to find every semantic bug or replace code review. It checks policy boundaries that should be explainable and repeatable in CI:
- did the PR stay inside its declared scope?
- did workflow permissions escalate?
- did agent control-plane files drift?
- did high-risk code change without matching test-file evidence?
- did MCP config changes get surfaced?
Use your LLM reviewer for judgment. Use Agent Gate for deterministic merge evidence.
AI agents can open pull requests. Tests do not always catch:
- out-of-scope edits
- workflow permission escalation
- agent control-plane drift
- missing test evidence
- MCP config drift
Human-readable output for demos:
pnpm --filter agent-gate build
node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/workflow-permission-escalationExample output:
Agent Gate: BLOCKED
ERROR workflow/permission-escalation
contents permission increased from read to write.
Path: .github/workflows/release.yml
ERROR workflow/dangerous-pattern
.github/workflows/release.yml contains a dangerous GitHub Actions workflow pattern.
Path: .github/workflows/release.yml
Machine-readable JSON report:
node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/workflow-permission-escalation --format jsonExpected result: Agent Gate reports a blocked PR with workflow/permission-escalation and workflow/dangerous-pattern findings.
Additional unsafe-pr-zoo demos:
agent-control-plane-drift: blocksAGENTS.mdchanges because they can change future agent behavior.out-of-scope-agent-edit: blocks a payment webhook edit outside the PR contract'sallowed_paths.missing-test-evidence: blocks an auth logic change without matching auth test changes.mcp-config-drift: blocks.mcp.jsonchanges because MCP config can change which tools an agent can call.
node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/agent-control-plane-drift
node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/out-of-scope-agent-edit
node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/missing-test-evidence
node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/mcp-config-driftStart in warn mode, learn your repo's risk profile, then turn proven policies into merge gates.
Add a checkout-free pull request workflow:
name: Agent Gate
on:
pull_request:
types: [opened, synchronize, reopened, edited, labeled, unlabeled, ready_for_review]
permissions:
contents: read
pull-requests: read
jobs:
agent-gate:
runs-on: ubuntu-latest
steps:
- uses: sjh9714/Agent-Gate@v0.2.2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
mode: warn
fail-on-block: falseStart with a small agent-gate.yml:
version: 1
mode: warn
contract:
required_for:
- agent
allow_missing_in_observe_mode: true
agent_detection:
labels:
- ai
- agent
- codex
branch_patterns:
- "codex/**"
- "ai/**"
high_risk_paths:
workflows:
paths:
- ".github/workflows/**"
severity: errorFor an AI-generated PR, add a small contract to the PR body:
<!-- agent-gate-contract
version: 1
agent: codex
task: update auth session handling
allowed_paths:
- src/auth/**
- tests/auth/**
required_evidence:
- matching auth tests changed
-->Read the first runs as observation, not proof of semantic correctness:
PASSED: safe to observeWARN: needs human decisionBLOCKED: must block once policy is enforced
The Markdown report leads with the human decision before the rule details. Example shape:
Agent Gate: NEEDS HUMAN DECISION
Why:
This PR changed `.github/workflows/release.yml` and added `secrets.*` usage.
Recommended next step:
Review the workflow change before merging.
Policy status:
Warning today; eligible to become a merge gate after tuning.
Add Agent Gate to a repository with a pull request workflow. No checkout step is required.
name: Agent Gate
on:
pull_request:
types:
- opened
- synchronize
- reopened
- edited
- labeled
- unlabeled
- ready_for_review
permissions:
contents: read
pull-requests: read
jobs:
agent-gate:
runs-on: ubuntu-latest
steps:
- uses: sjh9714/Agent-Gate@v0.2.2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
mode: warn
fail-on-block: falseAgent Gate loads policy from the PR base branch and does not execute PR branch code. Start with mode: warn and fail-on-block: false, tune the findings, then move to mode: block when ready.
To let Agent Gate create or update a PR report comment, add issues: write to the workflow permissions and set comment: true. Keep contents: read and pull-requests: read; no checkout step is needed. On fork pull requests, GitHub may still provide a read-only token, so comment failures are reported as warnings instead of failing the action.
permissions:
contents: read
pull-requests: read
issues: write
with:
comment: trueCreate agent-gate.yml in the repository root:
version: 1
mode: warn
contract:
required_for:
- agent
allow_missing_in_observe_mode: true
agent_detection:
authors:
- github-copilot[bot]
labels:
- ai
- agent
- codex
branch_patterns:
- "codex/**"
- "ai/**"
high_risk_paths:
workflows:
paths:
- ".github/workflows/**"
severity: errorTeams can add auth, payments, infra, and agent-control-plane paths as their policy matures.
Current agent-gate.yml support is intentionally narrow: agent detection,
PR-body contracts, high-risk paths with matching test-file evidence, agent
control-plane paths, and GitHub Actions workflow rules. File-based contracts,
risk budgets, dependency drift, claim-vs-CI evidence, reviewer requirements,
and rollback-plan requirements are planned areas and are rejected today instead
of being accepted as no-op settings.
packages/core: pure analysis engine, built-in deterministic rules, and JSON/Markdown report renderers.packages/cli:agent-gate replay <fixture-dir>for deterministic local fixture demos.packages/action: Node 24 GitHub Action package that reads pull request data through GitHub APIs and calls the core analyzer.
External users should prefer the root action with sjh9714/Agent-Gate@<ref>. The package-local action remains at packages/action/action.yml for this repository's own development workflow. Both use REST APIs only: they load agent-gate.yml from the PR base ref, read changed-file metadata and file contents from the API, run @agent-gate/core, write JSON/Markdown reports, set action outputs, write the job summary, and optionally upsert one marked PR report comment. They do not checkout the pull request or execute repository scripts.
Agent Gate runs against this repository's pull requests through .github/workflows/agent-gate.yml. The workflow uses sjh9714/Agent-Gate/packages/action@main, so pull requests do not execute Action code from their own branches while the action itself is under development. It starts in non-blocking warn mode while the project tunes early policy.
pnpm install
pnpm test
pnpm typecheck
pnpm lint
pnpm buildAgent Gate must not call LLMs at runtime, execute PR-controlled code, or load policy from an untrusted PR head. The core analysis package must remain independent from GitHub APIs.