| name | notion-policy-guardrails |
| description | Use when you need to govern Notion integrations at scale — set integration
naming standards, enforce page sharing policies, standardize property naming
and database schemas, and run access audits that scan which bots can reach
which pages. Trigger with phrases like "notion governance", "notion policy",
"notion naming convention", "notion access audit", "notion schema standard".
|
| allowed-tools | Read, Write, Edit, Bash(npx:*), Bash(node:*) |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
Notion Policy & Guardrails
Overview
Governance framework for Notion integrations at scale. Covers integration
naming standards, page sharing policy enforcement, property naming conventions,
database schema validation, and access audit scripts. Uses Client from
@notionhq/client for programmatic enforcement.
Prerequisites
@notionhq/client v2.x installed (npm install @notionhq/client)- Python:
notion-client installed (pip install notion-client)
NOTION_TOKEN environment variable set (admin-level integration recommended for audits)- CI/CD pipeline (GitHub Actions examples provided)
Authentication
All scripts authenticate with a Notion internal integration token read from
the NOTION_TOKEN environment variable — never hardcode it. Create the token at
notion.so/my-integrations, share the target pages/databases with the integration,
and inject the token via CI secrets (e.g. secrets.NOTION_AUDIT_TOKEN). Audit
scripts want a broadly-shared admin integration; runtime bots want the narrowest
sharing scope that works. Token rotation is tracked in Step 1 (max 90 days).
Instructions
The workflow has three stages. Each stage's full enforcement code (TypeScript +
Python) lives in references/implementation.md —
the skeletons below show the shape; drill into the reference for the complete
functions.
Step 1: Integration Naming Standards and Token Management
Establish a {team}-{env}-{purpose} naming convention (e.g. eng-prod-sync) so
teams can identify which bot accessed what, validate it at startup, and track
token rotation (max 90 days). Core check:
function validateIntegrationName(name: string): string[] { }
Full IntegrationConfig, startup validation, and checkTokenExpiry registry:
references/implementation.md § Step 1.
