> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/_mcp/server.

# Notion

> Connect Notion to sync Pensar findings into a database and keep their status in step

# Notion Integration

Pensar Console integrates with Notion to file security findings as pages in a Notion database and keep their status in sync. The integration uses a **workspace-level OAuth app** — you authorize Pensar once, and there are no internal integration tokens to create or rotate.

> **Note**
>
> Notion's consent screen is where you choose which databases Pensar can write to. Pensar can only see and write to what you share there, so the integration never has access to the rest of your Notion workspace.

## Prerequisites

Before connecting Notion, ensure you have:

1. **A Notion workspace** where you can authorize an integration
2. **A database** for findings to land in, with a **Status** property (Notion's status type, not a plain select)
3. **Admin or owner access** to the Pensar Console workspace you want to connect

## Connecting Notion

1. Navigate to **Settings** → **Integrations** → **Issue tracking** in your Pensar Console workspace
2. Find the **Issue sync** card and locate the **Notion** section
3. Click **Connect Notion**
4. On Notion's consent screen, select the databases Pensar may write to and approve
5. You'll be automatically redirected back to Pensar Console with Notion connected

Once connected, the Notion section shows the connected workspace.

### Permissions

Notion does not use fixed OAuth scopes. Access is decided by what you select during consent: Pensar can read and write only the databases you share with it, and nothing else. To grant access to another database later, reconnect and select it.

## What Gets Synced

Once connected and enabled, Pensar files each matching finding as a page in the routed database:

* The page **title** is prefixed with `[Pensar Security]`
* The **body** includes the severity, description, affected location, line numbers, branch, CWE classification, and a direct link back to the finding in the Pensar Console
* The **Status** property is set to an option in the **To-do** group, so findings arrive triaged rather than blank
* A **Severity** property is set when the database has a select column for it

Pensar looks for a select property named **Severity**, **Priority** or **Risk**, and fills it when one of its options matches the finding's severity (`Critical`, `High`, `Medium`, `Low`). If the column uses different option names, such as `P0`/`P1`/`P2`, Pensar leaves it empty rather than guessing.

> **Note**
>
> The page body is written once, when the finding is filed. Later changes to the finding in Pensar update its status but do not rewrite the page body. The link back to the Console always shows the current detail.

### Opening a finding in Notion

When a Notion page already exists for a finding, the finding's actions menu includes **View in Notion**. Otherwise you can file one from the same menu with **Open as Notion page**. That does not require auto-sync to be enabled, only that Notion is connected and a database is selected (the workspace default, or a per-repository override). If a page is already linked, Pensar opens it instead of creating a duplicate.

## Routing Findings to Databases

Pensar routes findings to Notion databases with a workspace default plus optional per-repository overrides.

### Default Database

1. In the **Notion** section, set the **Default database**
2. This is the fallback database Pensar files into for any repository without an override, and for findings that aren't tied to a specific repository

### Per-Repository Overrides

Each repository can override the default routing:

| Setting             | Description                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| **Sync to Notion**  | Toggle whether findings from this repository are filed as Notion pages                              |
| **Database**        | The Notion database findings from this repository are filed in (falls back to the default database) |
| **Severity Filter** | The minimum severity required before a finding is filed                                             |

> **Note**
>
> Select a database before enabling sync for a repository. Repositories without an override inherit the workspace default.

## Backfilling Existing Findings

Turning on sync only affects findings discovered from that point on. To file findings you already have, use **Sync existing findings** in the **Issue sync** card. Pensar files every open finding that meets the routing and severity rules, skipping any that already has a linked Notion page.

## Two-Way Status Sync

### Pensar to Notion

When a finding's status changes in Pensar, the linked page's **Status** property is updated. This happens wherever the change is made: the console, the REST API, the CLI, MCP, a retest, or a merged pull request. A change that came from Notion itself is not sent back to it.

| Pensar status  | Notion status group |
| -------------- | ------------------- |
| Open           | To-do               |
| In review      | In progress         |
| Closed         | Complete            |
| False positive | Complete            |

Pensar matches on Notion's status **groups** rather than the option names inside them, so renaming your board's columns does not break sync. For a false positive, Pensar prefers an option in the Complete group whose name reads as a dismissal (`Cancelled`, `Won't do`, `Duplicate`, `Invalid`) and falls back to the first option in the group.

### Notion to Pensar

Status changes made in Notion flow back automatically through a webhook subscription on the Pensar Notion integration:

| Notion status group | Pensar status |
| ------------------- | ------------- |
| To-do               | Open          |
| In progress         | In review     |
| Complete            | Closed        |

Moving a page to a dismissal-named option in the **Complete** group marks the finding a **false positive** instead of closed.

> **Note**
>
> Inbound reflection can be turned off per provider with **Reflect status changes from Notion**, in the **Notion** section. With it off, Pensar remains the source of truth: findings still sync outward to Notion, but changes made in Notion are ignored.

## Disconnecting Notion

To remove the Notion integration:

1. Navigate to **Settings** → **Integrations** → **Issue tracking**
2. Find the **Notion** section in the **Issue sync** card
3. Click **Disconnect**

Disconnecting revokes Pensar's access token for your Notion workspace.

> **Warning**
>
> Disconnecting Notion stops Pensar from filing new findings as Notion pages and ends two-way status sync. Existing Notion pages are left in place.

## Troubleshooting

### Connection Failed

If the OAuth authorization fails:

1. Ensure you're signed in to the correct Notion workspace
2. Confirm you selected at least one database on the consent screen
3. Verify you have admin or owner access to the Pensar Console workspace
4. Try the **Connect Notion** flow again from **Settings** → **Integrations** → **Issue tracking**

### Database Not Listed

If the database you want doesn't appear in the picker, Pensar wasn't granted access to it during consent. Reconnect Notion and select it on the consent screen.

### Pages Not Being Created

If findings aren't appearing in Notion:

1. Confirm a **Default database** is set, or that the repository has a database override
2. Check that **Sync to Notion** is enabled for the repository
3. Verify the finding's severity meets the repository's **Severity Filter**

### Status Not Set on New Pages

If pages arrive with an empty Status, the database has no **Status** property. Notion's status type is distinct from a plain select; a select named "Status" will not be used.

### Status Changes Not Syncing

If moving a page to Done doesn't resolve the Pensar finding:

1. Confirm the page was originally filed by Pensar — status sync only applies to synced findings
2. Check that **Reflect status changes from Notion** is enabled
3. Confirm the option you moved to belongs to the **Complete** group

## Need Help?

If you encounter issues setting up your Notion integration, please contact our support team at [team@pensar.dev](mailto:team@pensar.dev).