notion-policy-guardrails

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 <[e-mail]>
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:

// Must match: /^[a-z]+-[a-z]+-[a-z]+$/  →  eng-prod-sync
function validateIntegrationName(name: string): string[] { /* ... */ }

Full IntegrationConfig, startup validation, and checkTokenExpiry registry: references/implementation.md § Step 1.

Step 2: Page Sharing Policies and Property Naming Conventions