Deployment Guide - jre-notion-workers

Overview

Notion Workers are deployed to Notion’s infrastructure via the ntn CLI. Workers:

Run on Node.js ≥ 22 (managed by Notion)
Execute on-demand (not long-running servers)
Receive JSON input and return JSON output
Have access to a pre-authenticated Notion client

Notion Workers is currently in alpha. APIs and deployment behavior may change. Check makenotion/workers-template for the latest updates.

Prerequisites

Install ntn CLI

Follow the installation guide at makenotion/workers-template.

Authenticate

Ensure you’re authenticated with the ntn CLI:

ntn auth login

Verify local setup

Run tests and type checking:

bun test

Both must pass before deployment.

Deployment Process

Quick Deploy

The fastest way to deploy:

npm run deploy

This runs npm run build && ntn workers deploy automatically.

Manual Deploy

Build

Compile TypeScript:

npm run build

This runs tsc and must complete with zero errors.

Deploy

Deploy workers to production:

ntn workers deploy

The CLI will:

Package your workers
Upload to Notion’s infrastructure
Register the tools
Confirm deployment success

Verify

List deployed workers:

ntn workers list

You should see:

write-agent-digest
check-upstream-status
create-handoff-marker

Setting Production Secrets

Before first deployment, configure production secrets:

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

Use production credentials, not test credentials. Never commit secrets or share them in logs.

List Configured Secrets

ntn workers secrets list

Update a Secret

ntn workers secrets set NOTION_TOKEN=new_token_value

Updating a secret requires redeployment for the change to take effect.

Testing Deployed Workers

Invoke a Worker

Test a deployed worker with sample input:

ntn workers invoke write-agent-digest --input '{
  "agent_name": "Inbox Manager",
  "run_timestamp": "2026-03-04T10:30:00Z",
  "status_type": "sync",
  "status_value": "complete",
  "sections": [
    {
      "heading": "Summary",
      "content": ["Processed 5 emails"]
    }
  ]
}'

View Logs

Monitor worker execution:

ntn workers logs

Filter by worker name:

ntn workers logs --worker write-agent-digest

Log Retention

Check the makenotion/workers-template documentation for current log retention policies.

Deployment Checklist

Before deploying to production:

Tests Pass

bun test

All tests must pass with zero failures.

Type Check Passes

npm run check

Must exit with no errors. strict: true is enforced.

Build Succeeds

npm run build

TypeScript compilation must complete successfully.

Secrets Configured

ntn workers secrets list

Verify all required secrets are set:

NOTION_TOKEN
DOCS_DATABASE_ID
HOME_DOCS_DATABASE_ID
TASKS_DATABASE_ID

README Updated

Ensure the README documents:

Input/output schemas for each worker
When agents should call each worker
Any new features or breaking changes

Worker Platform Constraints

Runtime Environment

Node.js ≥ 22

Managed by Notion’s infrastructure

No Bun APIs

Bun.file(), Bun.serve(), etc. won’t exist

ESM Only

"type": "module" in package.json

TypeScript

Compiled to JavaScript before deployment

Execution Limits

Timeout: Workers must complete within the platform timeout (typically 30-60 seconds). For large datasets, process in batches.

Design for Timeout Constraints

Break large operations into smaller chunks
Return progress indicators if needed
Consider pagination for database queries
Use early returns for validation failures

Input/Output Constraints

JSON only — No Date objects, Map, Set, etc.
Structured responses — Always return { success, ... } shape
No throwing — Return { success: false, error } instead
No raw Notion objects — Map to your own types

Worker Design Rules

1. Atomic Operations Only

One tool = one concern. Good:

write-agent-digest — Creates one digest page
check-upstream-status — Checks one agent’s status
create-handoff-marker — Creates one handoff record

Bad:

A single worker that writes digests AND creates handoffs

2. Idempotent by Default

Same input twice should produce the same result or safely skip. Example: create-handoff-marker has a circuit breaker — no duplicate handoff within 7 days.

3. No Side Effects on Dry Run

If a future worker supports dryRun: true, it must not write to Notion.

4. Structured Return Values

Always return typed objects:

// Good
return { 
  success: true, 
  page_id: 'abc123', 
  page_url: 'https://...' 
};

// Bad
return 'abc123';

5. Timeout-Aware Processing

For large datasets:

Process in batches
Return progress indicators
Consider pagination

Common Issues

Build fails with type errors

Solution:

Run npm run check locally
Fix all TypeScript errors
Ensure strict: true is maintained
Rebuild with npm run build

Worker times out in production

Solutions:

Profile execution time locally
Break operations into smaller batches
Optimize Notion API calls (fewer queries)
Check for infinite loops or blocking operations

Secrets not found at runtime

Solutions:

Verify secrets are set: ntn workers secrets list
Check secret names match exactly (case-sensitive)
Redeploy after updating secrets
Use src/shared/notion-client.ts to read from process.env

Worker invocation fails with schema error

Solutions:

Validate input matches the tool’s JSON schema
Check for invalid types (Date objects, etc.)
Review input in .examples/ directory
Test locally with the exact input first

Monitoring & Debugging

View Recent Logs

ntn workers logs --tail 100

Debug a Specific Invocation

Invoke with verbose output

ntn workers invoke write-agent-digest --input @input.json --verbose

Check logs immediately

ntn workers logs --worker write-agent-digest --tail 50

Reproduce locally

Use the same input with local dev:

bun run dev
# Then test with the same input

Error Handling Pattern

Workers return errors in the response:

if (!isValidInput(input)) {
  return { 
    success: false, 
    error: 'Invalid agent_name: must be one of ...' 
  };
}

try {
  // Notion API call
} catch (err) {
  return { 
    success: false, 
    error: `Notion API error: ${err.message}` 
  };
}

Never throw errors to the caller. Always return structured error responses.

Rollback & Recovery

Rollback to Previous Version

The ntn CLI may support version history. Check current documentation:

ntn workers versions
ntn workers rollback --version <version-id>

Verify in makenotion/workers-template.

Emergency Shutdown

If a worker is causing issues:

Quick fix: Deploy a version that returns early with a maintenance message
Long-term: Fix the issue, test thoroughly, redeploy
Monitor: Watch logs after redeployment

CI/CD Integration

For automated deployments:

# Example GitHub Actions workflow
name: Deploy Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '22'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run tests
        run: npm run test:ci
      
      - name: Type check
        run: npm run check
      
      - name: Build
        run: npm run build
      
      - name: Deploy
        env:
          NTN_TOKEN: ${{ secrets.NTN_TOKEN }}
        run: ntn workers deploy

Store NTN_TOKEN and other credentials in your CI secrets, never in code.

Next Steps

Architecture

Understand the worker system design

Worker Reference

Detailed API documentation for each worker

Testing Guide

Test before deploying

Credentials

Manage production secrets

Get Started

Core Concepts

Workers

Guides

​Overview

​Prerequisites

​Deployment Process

​Quick Deploy

​Manual Deploy

​Setting Production Secrets

​List Configured Secrets

​Update a Secret

​Testing Deployed Workers

​Invoke a Worker

​View Logs

​Deployment Checklist

​Worker Platform Constraints

​Runtime Environment

Node.js ≥ 22

No Bun APIs

ESM Only

TypeScript

​Execution Limits

​Input/Output Constraints

​Worker Design Rules

​1. Atomic Operations Only

​2. Idempotent by Default

​3. No Side Effects on Dry Run

​4. Structured Return Values

​5. Timeout-Aware Processing

​Common Issues

​Monitoring & Debugging

​View Recent Logs

​Debug a Specific Invocation

​Error Handling Pattern

​Rollback & Recovery

​CI/CD Integration

​Next Steps

Architecture

Worker Reference

Testing Guide

Credentials

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Process

Quick Deploy

Manual Deploy

Setting Production Secrets

List Configured Secrets

Update a Secret

Testing Deployed Workers

Invoke a Worker

View Logs

Deployment Checklist

Worker Platform Constraints

Runtime Environment

Execution Limits

Input/Output Constraints

Worker Design Rules

1. Atomic Operations Only

2. Idempotent by Default

3. No Side Effects on Dry Run

4. Structured Return Values

5. Timeout-Aware Processing

Common Issues

Monitoring & Debugging

View Recent Logs

Debug a Specific Invocation

Error Handling Pattern

Rollback & Recovery

CI/CD Integration

Next Steps