Content pipeline: OAuth, Decap, and Git

This guide covers steps 1–3 of the homepage deploy pipeline: authentication, editing, and committing content.

OAuth login

Decap CMS needs a GitHub access token to commit markdown. Netlify Identity is the default hosted option — this stack uses a self-hosted Express gateway (gateway/) on your VPS instead.

Flow:

1. Editor opens /admin
2. Decap redirects to AUTH_GATEWAY_URL/api/auth
3. Gateway redirects to GitHub OAuth (repo, user scope)
4. GitHub callbacks to /api/auth/callback
5. Gateway exchanges the code for a token and postMessages it to the Decap popup

Required env vars on the VPS:

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
AUTH_GATEWAY_URL=https://your-domain

Create a GitHub OAuth App with callback URL exactly: https://your-domain/api/auth/callback.

The auth-gateway container listens on port 3000 inside Docker. Expose it only through your reverse proxy (Nginx Proxy Manager), not publicly on the host port.

Edit in Decap CMS

After login, editors use the visual UI at /admin. Collections map to src/content/:

• blog/ — MDX capability articles per locale
• faqs/ — JSON FAQ entries
• pages/ — optional static pages

public/admin/config.yml uses a deploy-time placeholder:

base_url: __AUTH_GATEWAY_URL__

The GitHub Actions deploy workflow substitutes the real gateway URL before docker compose build.

Collections are validated by Zod schemas in src/content.config.ts — invalid frontmatter fails at build time, not in production.

Commit to GitHub

When an editor saves, Decap commits directly to the configured branch:

• develop — test/staging environment
• main — production content (merge when ready)

No separate CMS database: content is the git repo. Review changes with normal PRs, branch protection, and code review.

Local dev without OAuth: edit files under src/content/ directly, or deploy to a test VPS and use the CMS there. OAuth requires a public HTTPS callback URL.

---

Next: Production deploy guide · Back to pipeline