A zero-database CMS for SSN Coding Club, and the GitHub Actions that run it

The SSN Coding Club portal has no database. Posts, roles, portal routes and images live in one Git repository, writers publish through pull requests they never have to open, and a single GitHub Actions workflow decides what gets validated and which of ten Vercel projects gets redeployed. This post takes the system apart one requirement at a time: how Git stands in for a database, how a draft becomes a pull request, how the server enforces who may approve what, and how one workflow ships only the apps that changed.

Here is the single most important request, the life of one article. Step through it before reading on; the rest of the post is the detail behind each step.

Understand the problem#

The club has eight technical verticals, a few hundred members who turn over every year, and no budget for a hosted CMS or someone to run a database. It wants a blog and a portal per vertical, writing that is reviewed by the right people, and a site that does not need an operator. The repo is blackscythe123/CC-Website-2026, a pnpm monorepo of Next.js apps, and the main portal is live at cc-main-portal.vercel.app.

Functional requirements#

1. A member writes an article in a rich editor, with images, without losing work if the tab closes.
2. Submitting creates a reviewable unit, and nothing is published until it is approved.
3. Reviewers see a queue, read the article and approve or request changes. Who may approve depends on who wrote it.
4. Approved articles appear on the right portals, and only the apps that need a rebuild are rebuilt.
5. An admin can change roles, and the change takes effect on the next decision.

Non-functional requirements#

1. Zero database. Nothing to host, back up or pay for. Git is the source of truth.
2. Auditable. Every article records who wrote it and who approved it, in history.
3. Fails closed. If the server cannot prove a request is allowed, it refuses.
4. Cheap to deploy. One push must not create ten Vercel deployments.
5. Survivable. Roles are data, not code, so a new committee changes a file, not a deploy.

Requirements: write | submit | review | publish | roles
Constraint:   no database, Git is the source of truth
Actors:       writer, reviewer, admin
Nothing designed yet.

The set-up#

Core entities#

• Post: a Markdown file with frontmatter, in content/verticals/<slug>/posts/ or content/club/posts/.
• Draft: a branch named draft/<vertical>/<slug>-<n> plus the pull request that carries it.
• Image: a file under apps/main-portal/public/uploads/, committed to the draft branch.
• Role: an entry in content/club/roles.json: superadmin, vertical head, deputy or member.
• Review: a pull request review pinned to a commit, summarised later in the squash commit's trailers.
• Portal: an entry in content/club/portals.json that maps an app to a vertical.

The interface#

The Studio is a Next.js app and its API is a handful of route handlers. There is no REST resource for a post, because a post is not a row; the routes are verbs over GitHub.

GET  /api/auth, /api/callback        GitHub OAuth login
GET  /api/auth/me                    who am I, with roles from main
POST /api/posts/draft                submit: branch + commit + pull request
GET  /api/posts/drafts/remote        list my cloud drafts (drafts/<login>/*)
POST /api/posts/drafts/remote        save a cloud draft, no PR
GET  /api/posts/reviews              the review queue, filtered by role
POST /api/posts/reviews              approve or request changes (pullNumber)
GET  /api/posts/manage               list published posts
DELETE /api/posts/manage             remove a published post
GET  /api/roles, POST /api/roles     read and write roles.json
GET/POST/PATCH /api/roles/requests   role applications

The data model#

The model is three JSON or Markdown schemas and one GitHub object. A post's frontmatter is validated by zod in CI; roles.json and portals.json are read by the apps at request or build time.

Build it one requirement at a time#

Requirement 1: write without losing work#

A Medium-style canvas with a split-screen preview needs to survive a closed tab and a power cut, and it cannot use a server table to do it. The answer is two layers. While typing, the draft is autosaved to the browser's IndexedDB, in a database called CodingClubCMS, under a key that includes the lower-cased GitHub login so two people sharing a laptop do not read each other's draft. When the writer wants the draft on another machine, Sync posts it to a route that pushes a branch named drafts/<login>/<slug>, with no pull request. Pending edits are flushed when the page is hidden or unloaded. Images stay in the browser, as base64 behind a blob: placeholder, until Submit.

1. Each keystroke updates the editor state; a two-second debounced autosave writes it to IndexedDB under active_draft:<login>.
2. Sync sends the markdown, metadata and pending images to the drafts/remote route with the writer's session token.
3. The route creates or updates the personal branch off main. It is not a pull request, so no one is asked to review it.

Requirement 2: submit as a pull request#

Submit must create something reviewable and keep main clean. The posts/draft route verifies the session, checks that the user has push permission on the repository, checks the role and vertical, and then calls createDraftAndPullRequest. That function reads the head of main, creates draft/<vertical>/<slug>-<n>, commits each image and then the post to that branch, and opens a pull request into main with an overview and a governance checklist as its body.

1. The Submit drawer collects the vertical, summary and tags and posts the draft to the route.
2. The route cuts the draft branch from the current head of main and commits images then the post, authored as the writer.
3. It opens the pull request feat(<vertical>): <title> into main.
4. The workflow's first job runs on the pull request and reports validation and build status.

Requirement 3: approval enforced by the server#

Reviewers work in the Studio's Reviews page, which lists open pull requests and shows who still has to approve. The browser never decides anything. The posts/reviews route takes a pull request number and an action; it derives the rest, as the next section shows. When the quorum is met it records a review pinned to the head commit, squash-merges that commit and deletes the draft branch.

1. The Reviews page lists the queue; the writer sees their own pull requests, a head or deputy sees their verticals, a superadmin sees all.
2. On approve, the route reads roles.json from main with no caching, so a removed reviewer loses authority at once.
3. It fetches the pull request, files and commits from GitHub, checks the quorum and merges the reviewed commit.
4. The merge becomes one squash commit on main with two trailers, and the draft branch is removed.

Requirement 4: publish only what changed#

A push to main starts the workflow. Vercel's own Git integration is turned off in every app's vercel.json, so the workflow is the only thing that deploys. It validates, plans and then deploys a matrix of changed apps.

1. The merge commit lands on main and triggers content-ci.yml.
2. Job 1 re-validates content and commit policy and smoke-builds every app.
3. Job 2 finds each app's last good deploy and prints the list of apps to ship as JSON.
4. Job 3 builds and uploads each listed app in parallel with the Vercel CLI.
5. The portals serve the new build.

Deep dives#

Deep dive 1: Git as the database#

Deep dive 2: the draft branch and pull request publish flow#

The branch name is the draft's identity: draft/<vertical>/<slug>-<n>, where n is the last five digits of the millisecond timestamp. The example from the real submission shown earlier is draft/full-stack/your-first-pull-request-a-beginner-s-guide-to-git-30709, which became pull request #28. When a reviewer asks for changes, the writer revises and resubmits with the same pull request number and branch; the route verifies that the branch really belongs to that pull request and that the caller is its author or a superadmin, then adds a commit and posts a comment so reviewers know there is something new.

Deep dive 3: role and approval rules enforced server-side#

The quorum depends on who wrote the article:

Three details carry most of the weight. First, the vertical is read from the file path of the article inside the pull request, not from the title or the branch name; the queue page guesses it from the title for display, but the approval path does not. Second, a pull request may contain exactly one article file in the vertical under review plus uploads and nothing else, checked by two regular expressions, so a crafted pull request cannot sneak a change to roles.json through an approval meant for an article. Third, self-review is refused by exclusion: the pull request opener, the frontmatter author and every commit author on the branch are all excluded, so adding a commit to someone else's pull request disqualifies you from approving it.

Deep dive 4: the single workflow, validate, commit policy, then deploy what changed#

There is one workflow file, .github/workflows/content-ci.yml, named "CI - Content Schema & Monorepo Build". It runs on pushes and pull requests to main, and on manual dispatch with a deploy_all switch that ignores the diff. A concurrency group per workflow and ref cancels superseded runs everywhere except on main. It has three jobs.

Job 1, validate-and-test, runs on every pull request and push. It checks out with full history, sets up Node 24, runs scripts/verify-commit.mjs, installs with pnpm, runs pnpm run test:content and then pnpm run build as a smoke build. The commit check is a policy script that the repo also installs as a local commit-msg hook: a single-line subject under 25 words, only Co-authored-by trailers with real human emails, no AI assistant names, with merge, revert and fixup commits exempt. The CMS's own Authored-by and Approved-by trailers are the only place a users.noreply.github.com address is accepted, and a regular expression pins their exact shape. The content check applies the zod schema, checks that slugs are kebab-case and unique within a vertical, validates portal ids against portals.json, and rejects blob: and data: image URLs.

Job 2, detect-changed-apps, runs only on main. The goal is written in the YAML itself:

# CD: Vercel Git auto-deploys are disabled (apps/*/vercel.json). Production
# deploys happen here, only for apps whose files changed since that app's
# last successful deploy, so one push no longer creates 10 Vercel deployments.

find-deploy-bases.mjs reads the last 60 runs of this workflow on main through the Actions API and, for each deployable app, records the head commit of its most recent successful "Deploy <app>" job. detect-changed-apps.mjs then diffs each app against its own base, using rules in scripts/lib/affected-apps.mjs:

Job 3, deploy, is a matrix over the JSON list from job 2, with fail-fast: false so one broken app does not stop the others, and a per-app concurrency group that never cancels an in-flight deploy:

strategy:
  fail-fast: false
  matrix:
    app: ${{ fromJSON(needs.detect-changed-apps.outputs.apps) }}
concurrency:
  group: vercel-deploy-${{ matrix.app }}
  cancel-in-progress: false

Each leg installs the Vercel CLI, links the project cc-<app>, pulls production settings, runs vercel build --prod on the Actions runner and uploads the result with vercel deploy --prebuilt --prod. Building in Actions and uploading the prebuilt output makes the CI run the single place where a deploy happens and fails. The token is a repository secret, VERCEL_TOKEN.

Deep dive 5: image handling#

Accepted images are renamed to <timestamp>-<sanitised-base>.<ext> with everything outside a-z0-9_- replaced, which closes off path tricks, and committed with a chore(media): upload ... message. The merge handler later accepts only files matching apps/main-portal/public/uploads/[A-Za-z0-9._-]+ as uploads in a pull request, so an image path cannot be used to smuggle a file into another directory.

Deep dive 6: concurrency and conflicts#

Most of the conflicts are designed away by layout. Each submission adds one new file at its own path, and uploaded images have unique timestamped names, so two pull requests rarely touch the same file and merge cleanly in any order. When two writers pick the same slug in the same vertical, the second pull request adds a file that already exists on main and GitHub refuses to merge it; the failure message returns to the reviewer. The remaining cases are about ordering.

The workflow side follows the same logic. The top-level concurrency group cancels superseded runs on a pull request but never on main, so a merge is not abandoned by a later push. Each deploy leg has its own group, vercel-deploy-<app>, with cancellation off, so two runs cannot deploy the same app at once and an in-flight deploy is never killed halfway. GitHub keeps one running and one pending job per group and replaces an older pending job with a newer one. That is acceptable here because every run checks out its own commit and diffs against the app's last good deploy, so the newest pending run covers what a replaced one would have shipped.

The final design#

A single request, then a single rebuild:

1. The writer submits. The draft route checks session, repo permission, role and vertical.
2. Each image is validated by type, size and magic bytes, and committed to the draft branch.
3. The post and its images sit on draft/<vertical>/<slug>-<n> and a pull request is opened; job 1 runs on it.
4. A reviewer approves. The review route reads live roles, the pull request and its commits from GitHub.
5. The file check confirms one article in the right vertical, and the authority check returns merge, count deputies or a refusal.
6. The squash merge of the reviewed sha writes the trailers and deletes the draft branch.
7. The push to main runs the workflow, which diffs each app against its own last good deploy.
8. One Vercel deploy leg runs per changed app. The rest are skipped.

What I would change#

• Make validation a required check. Branch protection requires one approving review and no status checks, and does not require code-owner review. The quorum lives in the Studio, so a collaborator who merges on github.com can bypass it. I would require validate-and-test and code-owner review, and turn on stale-review dismissal.
• Freeze the install. The workflow installs with --frozen-lockfile=false, so CI can resolve a different tree than the lockfile. A frozen install makes the build reproducible.
• Tell the writer about a rejected image. Fail the submit with a message instead of skipping the file.
• Detect stale edits. Compare file hashes on revision, and serialise role writes so the fallback cannot overwrite an edit.
• Check every commit, not just the head. The commit-policy step inspects the latest commit message; on a branch with several commits only the last one is read.
• Staff the other seven verticals. Only full-stack has a head, deputies and members in roles.json, and the per-vertical subdomains are still to do. The seed post how-this-cms-works.md also still describes the old Decap flow.

Test yourself#