Protection types

1. 1. Sign in with GitHub and connect repositories.
2. 2. Add a marker (file, folder, or symbol) — examples below.
3. 3. Require the Holy Files check on your protected branch.
4. 4. Open a PR that touches a protected path; the steward approves in GitHub.

Protect an entire file. Put @holy in the first 12 lines. Works in any language that has comments. Removing the marker on a PR is also treated as a protected change.

Triggers a block when: the file is added, modified, renamed, or deleted while holy on the base and/or head of the PR.

// TypeScript / JavaScript
// @holy steward=@alice
// AI agents: billing config — do not merge without steward review.

export const billingRules = {
  requireApproval: true
};

# Python
# @holy steward=@alice
# Critical pricing constants.

TAX_RATE = 0.2

<!-- HTML / Markdown-style comments if your file supports them -->
<!-- @holy steward=@alice -->

Omit steward=… to use the fallback chain (repo default → org default → installer).

Protect a whole directory tree. Add a file named exactly .holy inside the folder. Every path under that folder is protected (including nested files).

Triggers a block when: any file under that folder is changed on a PR.

# src/billing/.holy
steward=@alice

AI agents: payments and ledger code.
Changes require human approval.

Team plan: create a steward team handle like @billing, then use the same syntax — steward=@billing.

Protect a single function or method without locking the whole file. Put @holy in the comment block immediately above the declaration.

Supported languages / extensions today:

• .js / .jsx — JavaScript
• .ts / .tsx — TypeScript
• .py — Python

Symbol kinds: function and method. Other languages fall back to file/folder markers only (no symbol scan).

Triggers a block when: body or signature changes, the symbol is renamed/deleted, the marker is removed, steward/message metadata changes, or a new holy symbol is introduced. If parsing fails on a file that still contains @holy, Holy Files fails closed and treats it as a protected file change.

// TypeScript — protect one function
/** @holy steward=@alice
 *  @holyReason Must stay consistent with settlement math.
 */
export function calculateDailyMilk(weight: number, hours: number): number {
  return (weight / hours) * 24;
}

// This function is not holy — free to edit
export function ordinary() {
  return 1;
}

# Python — protect one function
# @holy steward=@alice
# @holyReason Auth entrypoint
def authenticate(user_id: str) -> bool:
    return True

def helper():
    return 0

// Method on a class (JS/TS)
class Ledger {
  /**
   * @holy steward=@billing
   */
  postCharge(amount: number) {
    return amount;
  }
}

Markers always use the same shape: steward=@handle.

• steward=@alice — if there is no steward team named alice, that GitHub user must approve.
• steward=@billing — if you created a steward team with handle @billing, any team member's approval clears the check (Team plan).

Handles are unique per org. Prefer team names that won't collide with a GitHub login you also need as an individual steward.

Fallback order when a marker omits steward: repo default → org default → the GitHub user who enrolled the repo.

Org owners can override from the dashboard with a required reason (audited).

1. 1. Holy Files scans changed paths for file markers, folder .holy files, and symbols (supported languages only).
2. 2. It posts a required check named Holy Files and a PR comment listing missing stewards.
3. 3. It requests reviews from the steward user(s) or team members.
4. 4. An approving GitHub review from an allowed steward (or owner override) clears that requirement for the PR head SHA.

When you enroll a repository, Holy Files creates a branch ruleset that requires the Holy Files status check on your protected branch, so blocked pull requests cannot be merged. If your organization restricts that, the repository settings page shows a Require the Holy Files check button, and you can always configure it yourself in GitHub branch protection or rulesets.

Early access: Team features (unlimited seats, steward teams, audit export) are unlocked for free while we gather feedback. Planned paid Team pricing is $12/seat/month later. Enterprise features (SSO, GHE Server) remain contact-sales only.