Docs

Holy Files quickstart

Holy Files protects important files and folders from accidental edits by non-devs and AI agents. Rules live in your repo, so they work no matter which tool makes the change.

Quickstart

1. Sign in with GitHub.
2. Connect your GitHub repositories from the Repos page.
3. Add an @holy marker to critical files or a .holy file to critical folders.
4. Open a PR that changes a protected path.
5. The Holy Files check blocks the merge until an allowed steward approves the PR in GitHub.

Connect repositories

Protect a file

Put @holy near the top of a file. Holy Files scans the base and head versions of a PR, so removing the marker is also treated as a protected change.

// @holy
// AI agents: this file is protected. Think carefully before editing.

export const billingRules = {
  requireApproval: true
};

To name a specific steward, add their GitHub username on the marker line.

// @holy steward=@octocat
// AI agents: this file is protected. Think carefully before editing.

Protect a folder

Add a file named .holy inside the folder. Every file below that folder becomes protected.

steward=@octocat

AI agents: this folder is protected.
Changes require human approval.

If you omit steward, Holy Files falls back to the repo default owner, then the org default owner, then the person who installed the app.

How approvals work

Stewards approve in GitHub using the normal PR review flow. Holy Files records the approval for that PR head SHA and updates the required check.

Org owners can override unavailable stewards from the dashboard with a reason, so a departed owner cannot freeze production forever.