Repository Configuration
The structure of ghost.yml and security policies
Repository-wide policy lives in a ghost.yml file at the root of your repository.
Fields Reference
# ghost.yml
version: 1
# If true, the pre-push hook blocks pushes missing verified notes
required: false
# Reject PRs if AI-authored lines exceed this percentage
threshold: 80
# Action to take when threshold is crossed: "block" or "warn"
on_exceed: block
# Automatically post audit summaries to the GitHub Pull Request comment
pr_comment: true
# The official repository owner email (handles cryptographic controls)
owner: admin@example.com
# Exclude generated files from calculation models (similar to .gitignore)
ignore:
- "*.lock"
- "vendor/**"
- "dist/**"
- "**/__snapshots__/**"
# Unverified commits policy: "block", "warn", or "ignore"
unverified_policy: warn
# Fallback to older git-ai notes if ghost structures are missing
gitai_fallback: trueWhen true, the pre-push hook blocks pushes that lack ghost-verified notes. New contributors get a one-time grace period to install ghost before the gate activates.
The maximum percentage of AI-authored lines allowed in a PR. Default 80%. Set to 0 to block all AI code, or 100 to allow any amount.
block rejects the PR with exit code 1. warn posts a comment but allows merge.
When true, ghost posts a formatted attribution report as a PR comment after audit. Uses the GitHub API via the GITHUB_TOKEN.
Email address of the person authorized to run owner-only commands like ghost banish. Set during ghost init.
Glob patterns for files to exclude from attribution calculations. Same semantics as .gitignore. Use ghost banish and ghost banish --clear to manage these.
Controls how commits without ghost-verified notes are handled. block rejects, warn flags but allows, ignore skips the check entirely.
When true, ghost reads refs/notes/ai (git-ai format) as a fallback if no ghost note exists for a commit. Read-only — ghost never writes to git-ai refs.
Config Pinning
ghost.yml from the base branch (e.g. origin/main) using the --config-ref flag. Changes to ghost.yml inside a PR branch are ignored during audit. This prevents a PR author from lowering the threshold or disabling the policy to sneak AI code through.