Notion Multi-Environment Setup Skill

Notion Multi-Environment Setup

Overview

Configure separate Notion integrations for development, staging, and production. Each environment uses its own integration token, targets different databases, and applies environment-appropriate log levels and timeouts. This prevents dev data leaking into prod and enforces least-privilege per tier.

Prerequisites

Notion workspace(s) per environment (one workspace can serve dev/staging via separate integrations)
@notionhq/client v2+ installed (npm install @notionhq/client)
Python alternative: notion-client (pip install notion-client)
Secret management platform (AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault)
CI/CD pipeline with per-environment variable injection

Instructions

The build has three steps. The lean skeleton below is enough to follow the workflow end to end; the full walkthrough carries the complete TypeScript and Python factories, every secret-manager command, and the CI/CD workflow.

Step 1: Per-environment integrations and an env-aware client

Create one integration per environment at https://www.notion.so/my-integrations, each with capabilities scoped to the tier — dev gets full access, prod gets the minimum required:

| Environment | Integration | Capabilities | Timeout | Log Level | | ------------- | ------------- | -------------- | --------- | ----------- | | Development | my-app-dev | All (read+update+insert+delete) | 60s | DEBUG | | Staging | my-app-staging | Read + Update + Insert | 30s | WARN | | Production | my-app-prod | Minimum required only | 30s | ERROR |

A single client factory reads NODE_ENV (or APP_ENV), pulls the token and database IDs from the environment, and applies the per-tier log level and timeout. It throws a descriptive error when NOTION_TOKEN is missing so misconfiguration fails loudly:

export function createNotionClient(): Client {
  const config = getConfig(); // reads NODE_ENV, token, per-tier defaults
  return new Client({
    auth: config.token,
    logLevel: config.logLevel,
    timeoutMs: config.timeoutMs,
  });
}

Full TypeScript getConfig/getDatabaseId and the Python equivalent: implementation.md, Step 1.

Step 2: Secret management and environment files

Keep dev/staging tokens in git-ignored per-environment files (.env.development, .env.staging). Never store production tokens in files — put them in a secret manager and inject at deploy time:

# AWS example — prod secret stored once, injected by the platform
aws secretsmanager create-secret --name "notion/production" \
  --secret-string '{"token":"ntn_prod_...","tasks_db":"...","users_db":"..."}'

AWS Secrets Manager, GCP Secret Manager (with Cloud Run injection), and HashiCorp Vault commands: implementation.md, Step 2.

Step 3: Environment guards and CI/CD

Add guards so a destructive call cannot run in the wrong tier — requireNonProduction() blocks seeding/test writes in prod, requireEnvironment('production') gates migrations. A startup validator fails fast on missing vars and catches an obvious token/tier mismatch:

function requireNonProduction() {
  if (process.env.NODE_ENV === 'production') {
    throw new Error('Destructive operation blocked in production');
  }
}

Full guard set, startup validation, and the per-environment GitHub Actions deploy workflow: implementation.md, Step 3.

Output

Separate Notion integrations per environment with scoped capabilities
Environment-aware client factory (TypeScript and Python)
Secrets stored in platform-appropriate secret managers (never in files for production)
Startup validation that fails fast on misconfiguration
Guards preventing cross-environment mistakes (no prod data in dev, no test data in prod)
CI/CD pipeline deploying with per-environment secrets

Error Handling

| Issue | Cause | Solution | | ------- | ------- | ---------- | | NOTION_TOKEN not set | Missing env var | Check the per-environment .env file or secret manager config | | Wrong database in prod | Env var misconfigured | Add startup validation to compare token prefix with env | | Token for wrong environment | Secret manager mapping error | Validate token prefix at startup | | Dev data written to prod DB | Missing environment guard | Add requireNonProduction() to destructive operations | | 401 Unauthorized | Token revoked or expired | Regenerate at notion.so/my-integrations, update secret | | database_id not found | Page not shared with integration | Share target database with the correct env integration |

Examples

Two end-to-end examples live in examples.md:

Full initialization pattern — chains validateNotionConfig(), the client factory, and a live connectivity + database-access check into one initNotion() boot function.
Quick environment check script — a verify-notion-env.sh pre-deploy script that confirms the injected token authenticates and reports the workspace it points at.

# verify-notion-env.sh (excerpt) — confirm the injected token before deploy
curl -sf https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer ${NOTION_TOKEN}" \
  -H "Notion-Version: 2022-06-28" | jq '{name, type}'

Resources

Full implementation walkthrough — all code for Steps 1–3
Worked examples — init pattern + pre-deploy check script
Notion Create Integrations
Notion Authentication
12-Factor App Config
AWS Secrets Manager
GCP Secret Manager
HashiCorp Vault KV

For monitoring your Notion integration health across environments, see the notion-observability skill.

Agent Skills: Notion Multi-Environment Setup

Install this agent skill to your local

Skill Files