Notion Integration

Oversight syncs reviews and plans to Notion, creating structured pages under a configurable parent database. Reviews are posted with structured titles, and plans can be exported automatically on generation.

What Gets Synced

Two types of content are synced to Notion:

Content Type Task Type When
PR Reviews review Automatically after every review completes
Implementation Plans generate-plan When syncToNotion: true is passed
Arbitrary Pages create-notion-page On demand via API or chat

How Reviews Are Posted

When a PR review completes, the CLI output includes special HTML comments that the reviewer extracts:

Notion metadata in review output text
<!-- notion:page_id=abc123 -->
<!-- notion:page_url=https://notion.so/... -->

The review prompt instructs Claude to create a Notion page as part of the review process. The page is created as a child of the configured parent page (the "PR Reviews" database), with a structured title:

Example Notion page title text
PR Review: CopilotKit/CopilotKit #4250 — Fix streaming race condition

The review Markdown is converted to Notion blocks and stored as page content. The notion_page_id and notion_page_url are persisted on the task record in Supabase for cross-referencing.

How Plans Are Exported

When a plan is generated with syncToNotion: true, the runner calls the Notion API directly (no CLI involved) to create a page:

  1. The plan Markdown is chunked into Notion blocks using chunkMarkdownToBlocks()
  2. A page is created under the configured database with title format Implementation Plan — owner/repo
  3. The page ID and URL are stored on the task record
Block Chunking: Notion's API has a limit on block content size. The chunkMarkdownToBlocks() utility splits long Markdown content into appropriately sized paragraph blocks to stay within API limits.

Creating Arbitrary Pages

The create-notion-page task type lets you create any Notion page with a custom title and Markdown body. This is used by the CopilotKit chat assistant to save analysis summaries, comparisons, or any other generated content.

API Endpoint

Method Path Description
POST /api/copilot/create-notion-page Create a Notion page with custom content

Request Body

CreateNotionPageRequest ts
interface CreateNotionPageRequest {
  repoId: number;
  title: string;
  content: string;  // Markdown body
}

Response

CreateNotionPageResponse ts
interface CreateNotionPageResponse {
  taskId: string;
}

Configuration

Environment Variable Required Description
NOTION_API_KEY Yes Notion internal integration token. Create one at notion.so/my-integrations
NOTION_DATABASE_ID Yes The ID of the Notion database where pages are created. Found in the database URL: notion.so/{workspace}/{database_id}?v=...

Setting Up Notion

  1. Create a Notion integration with "Insert content" and "Read content" capabilities
  2. Create a database in Notion for oversight pages (it must have a title property)
  3. Share the database with your integration (click "..." → "Connections" → add your integration)
  4. Copy the database ID from the URL and set NOTION_DATABASE_ID
  5. Copy the integration token and set NOTION_API_KEY

Audit Trail

Every Notion page creation is recorded in the audit log with the action create-notion-page, including the task ID and page title. This provides a complete trail of what content was synced to Notion and when.