Skip to content

Add Decap CMS for governance team content editing#1191

Open
hummusonrails wants to merge 1 commit into
ArbitrumFoundation:mainfrom
hummusonrails:decap-cms-integration
Open

Add Decap CMS for governance team content editing#1191
hummusonrails wants to merge 1 commit into
ArbitrumFoundation:mainfrom
hummusonrails:decap-cms-integration

Conversation

@hummusonrails
Copy link
Copy Markdown

Summary

Adds a git-backed Decap CMS layer so the Arbitrum governance team can edit the governance docs through a browser, without touching git. This is the same CMS the governance team has been testing on a staging fork over the past several weeks and has fully approved; this PR moves it into the canonical docs repo.

CMS edits publish to main via Decap's editorial workflow and deploy through the existing Vercel pipeline.

What's included

  • static/admin/index.html — branded Decap CMS v3 entry point (loaded from CDN); injects base_url from the current origin at runtime
  • static/admin/config.yml — content schema: 5 collections mapped to the docs/ folders; repo: ArbitrumFoundation/docs, branch: main, publish_mode: editorial_workflow
  • api/auth.js, api/callback.js — GitHub OAuth handshake as Vercel serverless functions (the OAuth token is JSON-escaped to prevent XSS)
  • static/img/AF_vertical_stack.png — Arbitrum Foundation logo shown on the CMS login
  • vercel.json — adds a functions block for the api/ functions; the existing build and redirect config is unchanged
  • .env.example, .gitignore (adds .vercel)

Publish model

The governance team are prose editors, not a technical team. With editorial_workflow and branch: main, an editor drafts a change, marks it ready, and hits Publish, which merges the edit to main and triggers the normal Vercel deploy. No git knowledge required on their side.

Required setup before the CMS works (not in this PR)

  1. GitHub OAuth app — create one owned by the ArbitrumFoundation org (so it isn't tied to a personal account). Homepage https://docs.arbitrum.foundation, authorization callback https://docs.arbitrum.foundation/api/callback.
  2. Vercel env vars on the docs project (Production scope): GITHUB_OAUTH_CLIENT_ID, GITHUB_OAUTH_CLIENT_SECRET.
  3. Repo write access for governance editors. OAuth scope is public_repo (sufficient since this repo is public). Each editor authenticates as themselves, so commits are attributed to the individual editor.

Notes for reviewers

  • vercel.json: only the functions block was added. The build is intentionally left to the existing project configuration / framework auto-detection, so this PR does not change how the site builds. If the docs project relies on explicit build settings, adjust as needed.
  • Vercel preview deployments' deployment protection blocks the /admin/config.yml fetch; production is unaffected. Disable protection only if you want the CMS to work on previews too.
  • The /admin/ route is marked noindex.

Verification (after merge + setup above)

  • https://docs.arbitrum.foundation/admin/ loads and GitHub login succeeds
  • Editing a page and hitting Publish merges to main and deploys

Test plan

  • GitHub OAuth app created (org-owned), callback URL set
  • GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET set on the Vercel docs project
  • Governance editors have write access to this repo
  • /admin/ loads and login works on production
  • A test edit publishes to main and deploys correctly

git-backed decap cms so the governance team can edit docs through a
browser without touching git. adds the branded admin ui, content
collections schema mapped to the docs folders, and github oauth via
vercel serverless functions. cms publishes to main through the
editorial workflow. oauth client id and secret are supplied as vercel
env vars (see .env.example).
@vercel
Copy link
Copy Markdown

vercel Bot commented May 28, 2026

@hummusonrails is attempting to deploy a commit to the Arbitrum Foundation Team on Vercel.

A member of the Team first needs to authorize it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant