Skip to content

getting-started.md

Latest commit

 

History

History
116 lines (78 loc) · 2.65 KB

getting-started.md

File metadata and controls

116 lines (78 loc) · 2.65 KB

Getting Started

A 5-minute walkthrough.

1. Install

git clone https://github.com/a2z2k26/notion-github-sync.git
cd notion-github-sync
npm install

Or as a dependency in your own project:

npm install notion-github-sync

2. Create a Notion integration

  1. Visit https://www.notion.so/my-integrations
  2. Click + New integration
  3. Name it (e.g. "Bumba")
  4. Select your workspace
  5. Click Submit, then copy the Internal Integration Token (starts with secret_ or ntn_)

3. Share a page with the integration

The integration cannot access any pages until you explicitly share them.

  1. Open or create a page in Notion (e.g. "Bumba Projects")
  2. Click Share in the top-right
  3. Search for your integration name and click Invite
  4. Copy the page ID from the URL — it's the 32-character hex string after the page slug

Full walkthrough with screenshots: notion-setup.md.

4. Configure

cp .env.example .env

Edit .env:

NOTION_API_KEY=secret_…
NOTION_PARENT_PAGE_ID=…

5. Verify

npx notion-github-sync verify

Expected:

  Connected as: <integration name>
  Parent page is accessible

If you see Verification failed, the most common causes are:

  • API key is wrong or revoked → regenerate it
  • Page wasn't shared with the integration → re-share it
  • Page ID is malformed → 32 hex chars (with or without dashes)

6. First page

node examples/02-create-page.js

This creates a page in your Notion workspace using a mix of block types — heading, paragraph, divider, bullet list, callout. Open the URL in the script's output to see the result.

7. First database

node examples/03-create-database.js

This creates a "My Tasks" database with the built-in TASKS schema, including columns for Status, Priority, Assignee, Due Date, GitHub Issue link, and Last Synced.

The script prints the database ID — add it to your .env as NOTION_TASKS_DATABASE_ID to enable GitHub sync.

8. GitHub sync

Add a GitHub PAT (with repo scope) and a target repo to your .env:

GITHUB_TOKEN=<github-token>
GITHUB_REPO=owner/name
NOTION_TASKS_DATABASE_ID=…

Then:

node examples/04-github-sync.js

Or via the CLI:

npx notion-github-sync sync -r owner/name -d <database-id>

This pulls all open and recently-closed issues from the repo into your Notion database, creating new pages or updating existing ones based on GitHub Number.

Where to next