Setup
The stable architecture is simple: schedule a run, export snapshots, commit to a private repo, and notify on failures. Keep each run idempotent so retries do not create duplicate or noisy commits.
Treat this as a production job. Add timeout bounds, explicit failure notifications, and logs that include run context (workspace, page count, changed files, and missing access warnings).
name: notion-backup
on:
schedule:
- cron: "0 3 * * *"
workflow_dispatch:
jobs:
backup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run backup:notionPitfalls
Most DIY systems fail from missing operational controls, not from missing export code. Silent gaps usually come from one of these issues.
- No alerting when workflow runs fail or partially complete.
- No retry/backoff strategy for rate limits and transient API failures.
- Non-deterministic output paths that make commit diffs noisy.
- Missing Notion integration sharing for key pages/databases.
Security
Keep credentials scoped and revocable. Prefer OAuth-based access over session cookies, and keep destination repos private by default.
- Use GitHub Secrets for all credentials.
- Restrict app permissions to the minimum required scopes.
- Store backups in a private repo with explicit collaborator access.
- Log and alert when integration access changes.
FAQ
Is GitHub Actions a good way to back up Notion?
It can be — if you also implement alerts, retries/backoff, and stable output. Most DIY failures come from silent breakage (auth, rate limits, missing access).
Where do I store secrets?
Use GitHub Actions Secrets (or environment secrets). Never commit tokens into the repository.
Why do DIY backups create noisy diffs?
Because outputs are not deterministic. Normalizing export paths and formats keeps diffs meaningful.
How do I know the job is still working?
You need notifications on failure plus a way to detect access loss or partial exports. Without alerts, you’ll get backup gaps.
When is paying for SaaS worth it?
When you want set-and-forget reliability: OAuth-based auth, retries/checkpoints, clean diffs, and alerts so backups don’t fail silently.