Pages CMS: a GitHub-native editor for static site content

The problem Pages CMS solves: content edits without a Git client

Static site generators keep content as files. That is the point of them. It is also the friction: a writer who wants to fix a typo has to clone a repository, edit Markdown, commit, push, and wait for a build. Pages CMS removes the clone-and-push step by putting an editing interface directly on top of the repository. The README describes it as "an open source CMS for GitHub repositories" that is "especially well suited for static sites and content-driven apps built with tools like Jekyll, Hugo, Next.js, Astro, VuePress, and similar stacks."

The audience is narrow and specific. It is not for sites whose content lives in a database, and it is not for teams that want to leave GitHub. It is for the case where the repository is already the source of truth and the missing piece is a form-based editor, media handling, and a login for people who do not use Git. The repository topics list reads like a compatibility statement: 11ty, astro, docusaurus, eleventy, gatsby, hugo, jekyll, nextjs, vitepress, vue, vuejs, vuejs3, vuepress.

How Pages CMS reads and writes your repository

The mechanism is a GitHub App plus a PostgreSQL database. The App is what grants the CMS permission to read and write repository contents on behalf of your installation; the database stores application state such as accounts, sessions and collaborators. The application itself is a Next.js project, which is why the repository layout includes app/, components/, contexts/, fields/, hooks/, lib/ and db/ directories alongside a drizzle.config.ts and a proxy.ts.

That split matters when you evaluate hosting. The hosted version at app.pagescms.org runs the whole stack for you. A self-hosted install means you own Postgres, the environment variables, and the GitHub App credentials. The README is explicit that the local development copy is exactly that: a development copy. It lists PostgreSQL, a GitHub App, a local .env.local and the checked-out repository as the four things you need.

A detail worth noticing is the caching layer. The package.json exposes a db:clear-cache script, and the README points to a caching documentation page. Cached repository state is an implementation choice that improves response times, but it also means a stale cache is a real failure mode you may have to clear rather than a theoretical one.

Installing Pages CMS locally and editing your first entry

The README's quick start assumes Docker for the database and npm for everything else. Clone the repository first, then start PostgreSQL 16 with the credentials the environment file will reference.

git clone https://github.com/pagescms/pagescms.git
cd pagescms

docker run --name pagescms-db -e POSTGRES_USER=pagescms -e POSTGRES_PASSWORD=pagescms -e POSTGRES_DB=pagescms -p 5432:5432 -d postgres:16

Install dependencies, then create .env.local. The README gives DATABASE_URL, BETTER_AUTH_SECRET and CRYPTO_KEY as the minimum, with BASE_URL and ADMIN_EMAILS as optional additions.

npm install

DATABASE_URL=postgresql://pagescms:pagescms@localhost:5432/pagescms
BETTER_AUTH_SECRET=your-random-secret
CRYPTO_KEY=your-random-secret

Generate the secrets rather than typing them. The README suggests openssl rand -base64 32. Next, create the GitHub App with the bundled helper script, which takes the base URL of your local instance.

npm run setup:github-app -- --base-url http://localhost:3000

The helper accepts --owner-type personal|org, --org <slug>, --app-name, --env and --no-open. Run the migrations, then start the dev server.

npm run db:migrate
npm run dev

What you should see is the app on localhost:3000 with a sign-in path backed by the GitHub App you just created. The first real use is signing in, pointing the CMS at a repository, and editing one Markdown file to confirm that a commit lands in GitHub. If you need GitHub webhooks to reach a local instance, the README says to use a public tunnel URL as the helper's --base-url.

Where Pages CMS stops: GitLab, schema control and cache state

The most concrete limitation is the GitHub-only model. The project name, the GitHub App requirement, and the setup script all assume GitHub. A related search phrase asking about pagescms gitlab exists, but the README offers no GitLab path, and the authentication stack is built on @octokit/app and @octokit/rest. If your organization standardizes on GitLab, this is the wrong tool and no configuration flag changes that.

The second limitation is operational. Self-hosting Pages CMS means running PostgreSQL, keeping a GitHub App's credentials correct, and managing a build that runs database migrations as a postbuild step. That is a real service to operate, not a static file you drop on a CDN. The README's own framing supports this reading: the local copy is described as a development copy, and the hosted version is presented as the easiest way to get started.

The third is cache coherence. The existence of npm run db:clear-cache, described as the remedy when "cache state is known stale or corrupted", tells you the application keeps derived state that can drift from the repository. For a small site this is invisible. For a repository with frequent external commits, it is a thing you will eventually have to reason about.

Pages CMS versus Decap CMS and the Git-backed CMS field

The natural comparison is Decap CMS, and the difference is architectural rather than cosmetic. Decap CMS is a client-side admin panel that talks to the Git host directly from the browser; there is no server component and no database to run. Pages CMS puts a Next.js application and PostgreSQL between the editor and GitHub. That buys you server-side authentication through a GitHub App, a place to store collaborator records, and the ability to run the whole thing under your own domain with BASE_URL set to a single canonical URL.

It also costs you a deployment. If your goal is to add an editor to a Hugo site with the least possible infrastructure, the client-side model is simpler. If you want the CMS to be an application you control, with an admin allowlist via ADMIN_EMAILS and a database you can inspect, Pages CMS is the heavier and more controllable option. The same trade-off separates it from other Git-backed editors in the same category: the question is not which editor looks better, it is whether you want a server in the loop.

Maintenance, upgrades and the MIT licence

The last push to the default branch was on 2026-06-23, roughly three months before the time of writing, and the repository is not archived. Recent releases are close together: 2.1.8 on 2026-06-08 fixed collaborator access and GitHub rate-limit handling, 2.1.7 on 2026-06-04 simplified collaborator invite sign-in with OTP verification, and 2.1.6 on 2026-04-30 fixed GitHub auth duplicate email repair. Two of those three touch authentication and rate limits, which tells you where the sharp edges have been.

The upgrade cost is concentrated in the 2.x line. The README links a dedicated page for upgrading to 2.x, which implies the move from 1.x is not a drop-in. If you are running an older install, read that page before touching anything. Version 2.1.8 is the current release in package.json, and the build pipeline runs npm run db:migrate as a postbuild step, so a deploy will attempt schema migrations automatically. On a self-hosted instance, that means your database is part of every release.

The licence is MIT, applied to everything in the repository. MIT permits commercial use, modification and redistribution with the licence and copyright notice retained. That is a permissive arrangement, but it is not legal advice, and a hosted deployment still has to satisfy GitHub's own terms for the App you create.

Editorial conclusion

Pages CMS fits teams whose content already lives in a GitHub repository as Markdown and who want non-technical editors to change it without a pull request workflow. It does not fit anyone who needs GitLab support, a database-backed content model, or an editorial pipeline with scheduled publishing. Before adopting it, confirm that your content files sit in one repository, that you can create a GitHub App for the install, and that the 2.x upgrade notes match the version you are running.

Frequently asked questions

Official sources

1. hunvreus/pagescms on GitHub
2. License: MIT
3. Project website
4. README
5. Releases