Quick start · Policy reference · Recipes · Security model · Contributing
Changefence is a small, deterministic gate that answers a question tests and linters do not:
Did this change stay inside the boundary we agreed to?
It evaluates a Git diff against explicit limits for paths, file count, line churn, dependency manifests, binary files, test coupling, and high-risk zones. Its own code uses no model or network client, sends no telemetry, and has no third-party Go dependencies.
That makes it useful for pull requests created by people, scripts, dependency bots, and coding agents—anywhere a correct-looking change can still be unexpectedly broad.
Add a policy:
cp .changefence.example.json .changefence.jsonThen add the GitHub Action. A full checkout is required so Git can calculate the merge-base diff:
name: Changefence
on: [pull_request]
permissions:
contents: read
jobs:
scope:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: nintechio/changefence@v1For pull-request events, the action takes the base commit directly from GitHub's event payload and reads .changefence.json from that commit. A proposed change cannot point the check at its own weakened policy.
The first setup pull request is evaluated with conservative built-in defaults because the policy does not exist on the base branch yet. Review and merge that bootstrap change before making Changefence a required check. See installation and rollout.
{
"$schema": "https://raw.githubusercontent.com/nintechio/changefence/main/policy.schema.json",
"max_files": 12,
"max_additions": 500,
"max_deletions": 500,
"max_lines_per_file": 300,
"allowed": ["src/**", "tests/**", "docs/**"],
"forbidden": ["infra/prod/**"],
"protected": [
".changefence.json",
".github/workflows/**",
"CODEOWNERS",
"SECURITY.md"
],
"source_patterns": ["src/**"],
"test_patterns": ["tests/**", "**/*_test.*"],
"require_tests_for_source": true,
"allow_dependency_changes": false,
"allow_binary_changes": false,
"zones": [
{
"name": "database-migrations",
"patterns": ["db/migrations/**"],
"max_files": 2,
"max_additions": 200,
"protected": true
}
]
}Omitted fields keep their built-in defaults. A numeric limit of 0 disables that limit. Unknown fields, invalid globs, negative limits, duplicate zone names, and trailing JSON all fail closed.
Many policy checks load configuration from the checked-out pull-request branch. That lets the same change relax the rule it is about to violate. Changefence instead resolves the base commit first and reads policy with Git object access. The proposed worktree is used only as diff input.
With Go 1.22 or newer:
go install github.com/nintechio/changefence@latest
changefence -base origin/mainOr download a release archive and verify its checksum and provenance. See installation.
Useful output modes:
changefence -base origin/main -format text
changefence -base origin/main -format json
changefence -base origin/main -format markdown
changefence -base origin/main -format githubExit 0 means the diff is within policy. Exit 1 means one or more unapproved violations were found. Exit 2 means the repository, policy, event, or input could not be evaluated safely.
Changefence does not decide whether code is correct, secure, or well designed. It does not infer intent, assign risk with a model, or replace tests and review. It enforces the explicit scope contract before reviewers spend attention on correctness.
Protected-path approvals are available in the CLI for trusted orchestration, but intentionally are not exposed by the pull-request Action. A PR-controlled workflow is not a trustworthy place to grant its own exception. The security model explains safe exception patterns and remaining platform assumptions.
- Installation and rollout
- Complete policy and rule reference
- Monorepo, migration, infrastructure, and documentation recipes
- Output formats and automation
- Threat model and trust boundaries
Focused bug reports, policy recipes, and pull requests are welcome. Please read CONTRIBUTING.md, the community guidelines, and SECURITY.md before reporting sensitive issues.
MIT © Nintech Ltd