Decap CMS: A Git-Based Admin Panel for Static Sites

The problem Decap CMS solves: editing files without a database

Static site generators produce fast sites, but they leave a gap. The content is Markdown or front matter sitting in a repository, and the only way to change it is to edit a file, commit and push. That is fine for the developer who set the site up and awkward for everyone else.

Decap CMS fills that gap by being an editor that writes to Git. It is a single-page application that you pull into the /admin part of your site. It presents a UI for editing content stored in a Git repository. When a user navigates to /admin/ they are prompted to log in, and once authenticated they can create new content or edit existing content.

The audience is narrow and specific. It is a team that already runs a static site generator, already keeps content in Git, and wants a writer or marketing colleague to publish a post without learning the command line. It is not a general purpose content platform. There is no database, no content API for other applications to query, and no editorial workflow beyond what Git itself provides.

The project was formerly Netlify CMS, renamed to Decap CMS in February 2023 according to the README. That history matters when you read older tutorials or search for configuration examples, because most of the material published before that date uses the old name and the old package.

How the /admin single-page app talks to your repository

The mechanism is worth understanding before you install anything, because it explains most of the project's limits.

The CMS ships as JavaScript and CSS. In the quick install those assets load from a CDN, so the only things you add to your site are an HTML entry point at /admin and a configuration file. The application runs entirely in the browser. There is no Decap server sitting between the editor and your content.

What connects the browser to your repository is your Git host's authentication. The user logs in through that host, and the CMS then reads and writes files through its API on the user's behalf. This is why the README describes the flow as: a user navigates to /admin/, logs in, and then edits content. The commit that results comes from that user's credentials, not from a service account you control.

The content model lives in a YAML configuration file. You describe your collections and fields there, and the UI is generated from that description. The README also notes that you typically tweak the main layout of the CMS a bit to fit your own site, which is a polite way of saying the default styling assumes a fairly plain setup.

The repository layout confirms the scale of the thing. It is a monorepo with a packages directory, a pnpm workspace file, a lerna configuration, and nx for running tasks across packages. The package.json drives development with nx run-many, and the test suite spans Jest for unit tests and Cypress for end-to-end tests, including a mock server under cypress/utils. That is a substantial JavaScript codebase, not a small script.

Installing Decap CMS and publishing a first post

The README describes two installation paths. The quick one needs a single HTML file and a configuration file, with all CMS JavaScript and CSS loaded from a CDN. The advanced one requires a static site builder with a build system that supports npm packages, and gives more flexibility in return.

Start with the quick path. Create an HTML entry point at the /admin path of your site. The README's quick start guide is the authoritative source for the exact markup, and the shape of that entry point is a page that pulls the CMS into your site.

Next to it, add a YAML configuration file that describes the content model of your site. This is the file the README names as the place where collections and fields are declared, and it is the file that determines which Git repository the CMS reads and writes.

When you load the /admin/ path in a browser after deploying, you should be prompted to log in. After authenticating, your collections appear and you can create an entry. Saving it produces a commit on the repository named in the configuration.

That last step is the part people underestimate. The CMS does not store anything itself. If the commit does not land, nothing was saved. The README does not reproduce a full config.yml inline, so copy the working example from the documentation site rather than reconstructing it from memory.

Where Decap CMS is the wrong tool

The most common mistake is treating Decap CMS as a headless CMS. It is not one in the sense the term is usually used. There is no content API your application queries at runtime, because the content is compiled into your static site at build time. If you need a mobile app to fetch articles over HTTP, or a search index updated the moment an editor hits publish, this design cannot give you that.

Authentication is the second boundary. The user logs in through a Git host, which means publishing rights follow repository access. The README is explicit that centralized user management, advanced roles, a database proxy and premium support are what Decap Turbo is for. If your organisation needs an editor role that can draft but not publish, or an approval chain before content reaches production, the open source project does not provide it. You would be building that on top of Git permissions, and Git permissions are coarse.

Editorial workflow is the third gap. Because saving means committing, a half-finished draft is a commit on a branch. The project's own repository contains a CHANGELOG.md and semantic versioning, and releases are documented on the GitHub releases page, but the README does not document rollback or draft-review behaviour. Treat those as things to verify against the documentation site rather than assume.

Finally, scale. Every save is a Git operation against a host API. For a blog with a few hundred posts this is invisible. For a content set in the tens of thousands of files, the browser has to load and index what it needs, and the commit-per-save model gets noisy. The project does not claim to be built for that case.

Decap CMS vs TinaCMS, Sanity and Strapi

People search for Decap CMS alternatives constantly, and the comparison is genuinely clarifying because the three usual names differ in approach rather than in features.

TinaCMS also targets Git-backed content, but it adds a visual editing layer and a GraphQL API generated from your schema. The difference in approach is that Tina expects a build step and a schema definition in code, while Decap CMS is configured in YAML and loaded as a browser application. If you want editors to click directly on the rendered page, that is a different product category.

Sanity and Strapi are not Git-based at all. Sanity stores content in its own hosted dataset and exposes it through an API. Strapi is a self-hosted headless CMS with a database, an admin panel and a REST or GraphQL API. Both give you the roles, workflows and runtime queries that Decap CMS does not. The cost is that you now operate a database and a service, and your content no longer lives as files next to your code.

The trade is straightforward. Decap CMS keeps your content in your repository, which means your content is versioned by the same tool as your code, reviewed by the same pull requests, and deployable by the same pipeline. You pay for that with the absence of a runtime API and with authentication delegated to your Git host. If your site is a blog, a documentation set or a marketing site built by a static site generator, that trade is usually good. If your content needs to be queried by an application at runtime, it is not a trade at all; it is the wrong category of tool.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-18. That is three days before the date used for this review, so the project is being worked on. Releases follow semantic versioning, and the recent cadence shows a steady line: 3.16.0 on 2026-08-31, 3.16.1 on 2026-09-08, and a 3.17.0 beta on 2026-09-14. The README states that every release is documented on the GitHub releases page, so the upgrade path is at least written down.

Upgrade cost is real but bounded. The CMS is a browser application, so an upgrade changes what runs in your editors' browsers, not a server you operate. The risk surface is your configuration file and any custom widgets or layout tweaks you made, because those are the parts that touch internal APIs. Pinning to a stable minor version and reading the changelog before moving is the sensible posture. The 3.17.0 line is in beta, so a production site should stay on 3.16.x until it ships.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. The practical implication of MIT for a project like this is that you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice are preserved. The README links to a line-by-line explanation of the MIT licence rather than summarising it, and that is the right place to read the details. None of this is legal advice; if the licence terms matter to your organisation, have someone qualified read them.

The repository also carries a SECURITY.md and a CODE_OF_CONDUCT.md, which tells you there is a defined channel for reporting vulnerabilities. For a tool that holds write access to your content repository, that channel is worth knowing about before you deploy.

Editorial conclusion

Adopt Decap CMS if your site is already built by a static site generator, your content lives as files in Git, and the people editing it can be trusted with commit access through a Git host login. Do not adopt it if you need centralized user management, granular roles, a database proxy or premium support, because the README points those needs at Decap Turbo instead, and do not adopt it if your content must be queried at runtime by an application. Before committing, verify three things in your own repository: that your build system can serve the /admin/ path, that your Git host's OAuth flow is one the CMS supports, and that your content model can be expressed in the config's collections and fields. The version to pin is the current stable release rather than the 3.17.0 beta line.

Frequently asked questions

Official sources

1. decaporg/decap-cms on GitHub
2. License: MIT
3. Project website
4. README
5. Releases