Docs/Notion Database Setup

Notion Database Setup

Configure your Notion database for Clotion

Notion Database Setup

Clotion uses a Notion database to track tasks. This guide covers setting up your database and integration.

Creating a Notion Integration

1. Create the Integration

  1. Go to notion.so/my-integrations
  2. Click + New integration
  3. Fill in the details:
    • Name: Clotion
    • Logo: Optional
    • Associated workspace: Select your workspace
  4. Under Capabilities, ensure these are enabled:
    • Read content
    • Update content
    • Insert content
  5. Click Submit

2. Copy Your Token

After creating the integration:

  1. You'll see your Internal Integration Token
  2. It starts with secret_ (older integrations) or ntn_ (newer integrations)
  3. Copy it and add to your .env:
NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
NOTION_API_KEY=ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security: Never share this token. It provides full access to any database you share with the integration.

Setting Up Your Database

Option A: Create a New Database

  1. In Notion, create a new page
  2. Type /database and select Database - Full page
  3. Add a Status property

Option B: Use an Existing Database

If you have an existing task database, ensure it has a Status property.

Status Property Setup

Your database needs a Status property. Notion supports two types:

Status Type (Recommended)

The newer Status property type with built-in groups (To-do, In progress, Complete):

  1. Click + Add a property
  2. Select Status
  3. Edit the status options to match these names exactly:
    • Backlog (in To-do group)
    • ToDo (in To-do group)
    • In Progress (in In progress group)
    • In Review (in In progress group)
    • Done (in Complete group)

Select Type (Classic)

The classic Select property also works:

  1. Click + Add a property
  2. Select Select
  3. Name it "Status"
  4. Add these options exactly:
    • Backlog
    • ToDo
    • In Progress
    • In Review
    • Done

Important: Status names are case-sensitive. Use exactly ToDo (not Todo, To Do, or TO DO).

Custom Status Names

If your database uses different status names, configure Clotion to match:

NOTION_STATUS_BACKLOG=Not Started
NOTION_STATUS_TODO=Ready
NOTION_STATUS_IN_PROGRESS=Working
NOTION_STATUS_IN_REVIEW=Review
NOTION_STATUS_DONE=Complete

Sharing Your Database

The integration needs access to your database:

  1. Open your database in Notion
  2. Click ... in the top-right corner
  3. Scroll down and click Add connections
  4. Search for "Clotion" (your integration name)
  5. Click to add it

You'll see a confirmation that the integration was added.

Finding Your Database ID

From the URL

When viewing your database as a full page:

https://www.notion.so/myworkspace/abc123def456789012345678901234?v=...
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                 This is your database ID (32 characters)

From an Inline Database

If your database is embedded in a page:

  1. Click on the database
  2. Click ... → Open as full page
  3. Copy the ID from the URL

Add it to your .env:

NOTION_DATABASE_ID=abc123def456789012345678901234

Common Mistake: Don't confuse the page ID with the database ID. If you get "Provided ID is a page, not a database", you copied the wrong ID.

Auto-Created Properties

On first run, Clotion automatically creates these properties:

PropertyTypePurpose
BlockedCheckboxShows when Claude needs help
Current StatusRich textReal-time progress updates
Clotion IDRich textUnique task identifier
BranchRich textGit branch name
PR URLURLLink to GitHub pull request

These properties appear on your database automatically. You can:

  • Reorder them in the database view
  • Hide them from certain views
  • But don't rename or delete them while Clotion is running

Database Views

Recommended Board View

Set up a Kanban board view grouped by Status:

  1. Click + to add a new view
  2. Select Board
  3. Group by Status
  4. Order columns: Backlog → ToDo → In Progress → In Review → Done

Filtering Views

Create filtered views for different purposes:

Active Tasks:

  • Filter: Status is "In Progress" or "In Review"
  • Sort: By Clotion ID

Blocked Tasks:

  • Filter: Blocked is checked
  • Sort: By last edited

Testing Your Setup

  1. Start Clotion:

    clotion

  2. Check the logs for:

    INFO | Connected to Notion database
INFO | All required properties already exist
INFO | Initialized state for X pages
INFO | Clotion is running! Move a Notion card to 'Todo' to start.

  3. Create a test card:

    • Add a card to Backlog
    • Give it a title like "Test: Add hello world function"
    • Move it to ToDo

  4. Watch Clotion pick it up!

Troubleshooting

"Could not find database"

  • Verify the database ID is correct (32 characters)
  • Ensure the integration has been added to the database
  • Check that your API key is correct

"Property 'Status' exists but has type 'status' instead of 'select'"

This is just a warning, not an error. Clotion supports both the newer status type and classic select type.

"Provided ID is a page, not a database"

  • You copied a page ID instead of the database ID
  • Open the database as a full page and copy from that URL

"Permission denied"

  • Re-add the integration to your database
  • Verify the integration has Update content capability
  • Check that you're using the correct API key

Status changes not detected

  • Status names must match exactly (case-sensitive)
  • Check your Notion Status property for exact spelling
  • Common issue: ToDo vs Todo vs To Do

Multiple Databases

Clotion supports one database at a time. If you need multiple:

  1. Run separate Clotion instances
  2. Each with its own .env file
  3. Point to different databases and repos
Previous
Task Workflow
Next
Handling Blocked Tasks