Agent Gate – a deterministic CI firewall for AI-generated PRs
Agent Gate is a deterministic CI firewall for AI-generated pull requests. It checks PR contracts, risky paths, agent instruction drift, workflow permissions, and test evidence before merge. No runtime LLM calls or PR code execution.
Notifications You must be signed in to change notification settings
Fork 0
Star 1
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
27 Commits
27 Commits
.github/workflows
.github/workflows
docs
docs
fixtures/unsafe-pr-zoo
fixtures/unsafe-pr-zoo
packages
packages
.gitignore
.gitignore
.prettierignore
.prettierignore
AGENTS.md
AGENTS.md
CHANGELOG.md
CHANGELOG.md
LICENSE
LICENSE
README.md
README.md
action.yml
action.yml
agent-gate.yml
agent-gate.yml
eslint.config.js
eslint.config.js
package.json
package.json
pnpm-lock.yaml
pnpm-lock.yaml
pnpm-workspace.yaml
pnpm-workspace.yaml
prettier.config.cjs
prettier.config.cjs
tsconfig.base.json
tsconfig.base.json
Repository files navigation
No AI PR gets merged without proof.
Agent Gate is a deterministic CI firewall for AI-generated pull requests. It checks PR contracts, risky paths, agent instruction drift, workflow permissions, and test evidence before merge.
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.
Status
Agent Gate is pre-release. v0.1.0 is available as a GitHub prerelease. 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.1.0 or a pinned commit SHA. @main tracks ongoing development.
See docs/v0.1.0-release-notes.md and docs/release-verification-v0.1.0.md for release notes and verification.
See docs/repository-governance.md for recommended branch protection and release safety settings.
See docs/launch-announcement-draft.md for a reusable launch announcement draft.
Feedback on AI-generated PR safety policies is welcome in #27.
What It Catches
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.json changes that alter which tools agents can call.
Why
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
Replay Demo
Human-readable output for demos:
pnpm --filter agent-gate build node packages/cli/dist/main.js replay fixtures/unsafe-pr-zoo/workflow-permission-escalation
Example 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 json
Expected 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: blocks AGENTS.md changes because they can change future agent behavior.
out-of-scope-agent-edit: blocks a payment webhook edit outside the PR contract's allowed_paths.
missing-test-evidence: blocks an auth logic change without matching auth test changes.
mcp-config-drift: blocks .mcp.json changes 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-drift
Install
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/[email protected]
with: github-token: ${{ secrets.GITHUB_TOKEN }} mode: warn fail-on-block: false
Agent 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: true
Create 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: error
Teams can add auth, payments, infra, and agent-control-plane paths as their policy matures.
Packages
packages/core: pure analysis engine, built-in deterministic rules, and JSON/Markdown report renderers.
packages/cli: agent-gate replay for deterministic local fixture demos.
packages/action: Node 20 GitHub Action package that reads pull request data through GitHub APIs and calls the core analyzer.
Action Package
External users should prefer the root action with sjh9714/Agent-Gate@. 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.
Self-Dogfooding
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.
Commands
pnpm install pnpm test pnpm typecheck pnpm lint pnpm build
Principle
Agent 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.
About
Deterministic CI firewall for AI-generated pull requests
Topics
security
typescript
ai
ci
mcp
developer-tools
code-review
pull-requests
ai-agents
github-actions
github-action
coding-agents
Resources
Readme
License
MIT license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
1 star
Watchers
0 watching
Forks
0 forks
Report repository
Releases
1 tags
Packages 0
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
TypeScript 99.6%
JavaScript 0.4%