Skip to main content

​
Required Environment Variables

The workers require four environment variables to function:
VariablePurpose
NOTION_TOKENNotion integration token (never log or expose)
DOCS_DATABASE_IDDocs database ID (32-char hex, no dashes)
HOME_DOCS_DATABASE_IDHome Docs database ID
TASKS_DATABASE_IDTasks database ID (for handoff tasks)
Never commit .env or .env.local files — they are in .gitignore. Always keep production credentials separate from test credentials.

​
Credential Options

​
Option A: 1Password (Maintainers)

For team members with access to the 1Password vault, run the automated secret loader: 
bash scripts/load-secrets.sh
This script:
  • Fetches credentials from the “JRE Notion Workers - API Credentials” 1Password item
  • Generates a .env file with all required variables
  • Uses the “Dev” vault by default (override with OP_VAULT environment variable)
  • 1Password CLI (op) installed and authenticated
  • Access to the Dev vault (or specified vault)
  • The “JRE Notion Workers - API Credentials” item
See 1Password CLI documentation for installation.

​
Option A1: 1Password + Cursor Hooks

For Cursor users, this project supports 1Password Cursor Hooks to mount secrets without storing plaintext on disk.
1

Install Requirements

2

Configure 1Password Environment

In 1Password:
  1. Create an Environment (e.g., “Notion Workers”)
  2. Add a Mount .env file destination pointing to .env.local (or .env) in your project
  3. Add these fields to the Environment:
    • NOTION_TOKEN
    • DOCS_DATABASE_ID
    • HOME_DOCS_DATABASE_ID
    • TASKS_DATABASE_ID
See Locally mounted .env files.
3

Enable the Mount

In the 1Password app:
  • Navigate to Destinations
  • Find your local .env file destination
  • Toggle Enabled
  • Restart Cursor
4

Verify Hook Operation

The repository includes:
  • .cursor/hooks.json — Hook configuration
  • .cursor/hooks/1password/validate-mounted-env-files.sh — Validation script
  • .1password/environments.toml — Lists paths to validate (.env.local and .env)
When the Cursor Agent runs a shell command, the hook validates that mounted files are present and valid.
Logs are written to /tmp/1password-cursor-hooks.log. Enable debug mode by setting DEBUG=1.
Problem: The hook denies access and blocks commands.Solutions:
  1. Workspace Root: Open Cursor with this project folder as the workspace root:
    • File → Open Folder → jre-notion-workers
    • NOT a parent folder
    • The hook resolves .env.local relative to the workspace root Cursor sends
  2. Check Logs: Open the log file to see why it was denied:
    • File → Open File → /tmp/1password-cursor-hooks.log
    • Look for “Required local .env file is missing or invalid”
    • Verify the path matches your 1Password mount path exactly
  3. Verify Mount: Ensure the mount is enabled in 1Password app and the destination path is correct.

​
Option A2: 1Password CLI (op run)

For terminal use without Cursor hooks, use secret references with the 1Password CLI:
1

Create .env.1p file

The project includes a .env.1p file with 1Password secret references:
NOTION_TOKEN=op://Dev/JRE Notion Workers/NOTION_TOKEN
DOCS_DATABASE_ID=op://Dev/JRE Notion Workers/DOCS_DATABASE_ID
# ... etc
2

Run commands with op run

Use the provided scripts that wrap commands with op run:
bun run dev:1p
See Load secrets into the environment for more details.

​
Option B: Manual Configuration

For contributors without 1Password access, manually create a .env file:
1

Copy the example file

cp .env.example .env
2

Fill in values

Edit .env with your credentials:
# Production credentials
NOTION_TOKEN=secret_abc123...
DOCS_DATABASE_ID=abc123...
HOME_DOCS_DATABASE_ID=def456...
TASKS_DATABASE_ID=ghi789...
3

Verify configuration

Run the connection test:
bun run test:connection
Never commit .env — it is gitignored. Use .env.example as a reference template only.

​
Using .env.local

If you keep credentials in .env.local (e.g., exported from 1Password), that file is also gitignored. Development: 
bun run dev:local
Testing: 
bun run test:local
One-off commands: 
bun run --env-file=.env.local <script>

​
Test Environment Variables

For integration tests, use separate test credentials to avoid touching production data: 
# .env or .env.local
TEST_NOTION_TOKEN=secret_test_...
TEST_DOCS_DATABASE_ID=test_db_id...
Never use production values for test variables. Always use a dedicated test database.
Integration tests are automatically skipped if TEST_DOCS_DATABASE_ID is not set.

​
Deployed Worker Secrets

For production deployment, set secrets via the ntn CLI: 
ntn workers secrets set NOTION_TOKEN
ntn workers secrets set DOCS_DATABASE_ID
ntn workers secrets set HOME_DOCS_DATABASE_ID
ntn workers secrets set TASKS_DATABASE_ID
Secrets are available as process.env variables in the deployed worker runtime.

​
Safe to Commit

These files are safe to commit and are tracked in git:

.env.example

.env.1p (secret references)

scripts/load-secrets.sh

.cursor/hooks.json

.cursor/hooks/1password/*

.1password/environments.toml
Never commit:
  • .env
  • .env.local
  • Any file containing actual secret values

​
Security Best Practices

Never Log Tokens

Never log or expose NOTION_TOKEN in console output, errors, or debug statements.

Separate Environments

Keep test credentials completely separate from production credentials.

Use Shared Client

Always use getNotionClient() from src/shared/notion-client.ts — never hardcode tokens.

Validate on Start

Use test:connection scripts to verify credentials before running workers.

​
Next Steps

Setup Guide

Complete the local development setup

Testing Guide

Run tests with your configured credentials

Deployment

Deploy workers with production secrets

Build docs developers (and LLMs) love

Get started for freeTalk to us