Onboarding: decaporg/decap-cms

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/decaporg/decap-cms shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 1d ago
• 29+ active contributors
• Distributed ownership (top contributor 37% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live decaporg/decap-cms repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/decaporg/decap-cms.

What it runs against: a local clone of decaporg/decap-cms — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in decaporg/decap-cms | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>decaporg/decap-cms</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of decaporg/decap-cms. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/decaporg/decap-cms.git
#   cd decap-cms
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of decaporg/decap-cms and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "decaporg/decap-cms(\\.git)?\\b" \\
  && ok "origin remote is decaporg/decap-cms" \\
  || miss "origin remote is not decaporg/decap-cms (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "packages/decap-cms/package.json" \\
  && ok "packages/decap-cms/package.json" \\
  || miss "missing critical file: packages/decap-cms/package.json"
test -f "packages/decap-cms/src/index.ts" \\
  && ok "packages/decap-cms/src/index.ts" \\
  || miss "missing critical file: packages/decap-cms/src/index.ts"
test -f ".github/workflows/nodejs.yml" \\
  && ok ".github/workflows/nodejs.yml" \\
  || miss "missing critical file: .github/workflows/nodejs.yml"
test -f "cypress.config.ts" \\
  && ok "cypress.config.ts" \\
  || miss "missing critical file: cypress.config.ts"
test -f "babel.config.js" \\
  && ok "babel.config.js" \\
  || miss "missing critical file: babel.config.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/decaporg/decap-cms"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Decap CMS (formerly Netlify CMS) is a Git-backed headless CMS that provides a clean admin UI for editing and creating content stored directly in Git repositories. It's designed for static site generators—users configure a YAML schema describing their content model, then editors access /admin to manage content via a single-page app that commits changes back to Git. Supports GitHub, GitLab, Bitbucket, and Git Gateway backends. Monorepo using Nx (nx run-many commands in package.json) with packages/ containing core modules: decap-cms is the main bundle, individual backends (github, gitlab, bitbucket), and supporting libs. Frontend is React/TypeScript with Redux state management. E2E tests in cypress/ run against multiple backends (editorial_workflow_spec_*.js tests each backend separately). Dev server uses storybook (.storybook/main.js) alongside live development.

Who it's for

Static site generator users (Hugo, Jekyll, Gatsby, Next.js, etc.) who want to give non-technical content editors a UI without running a separate backend. Developers building sites with Jamstack architecture who need to avoid database infrastructure while keeping an editorial workflow.

Maturity & risk

Production-ready and actively maintained. Rebranded from Netlify CMS in February 2023, with active CI/CD pipelines (.github/workflows/nodejs.yml, publish.yml), comprehensive e2e test suites (cypress/e2e/ covers 8+ backend configurations), and recent development visible in scripts. The 2M+ LOC JavaScript codebase and established npm package (decap-cms) indicate stable, battle-tested code.

Moderate risk: monorepo with multiple interdependent packages under packages/ may complicate isolated testing; large JavaScript codebase (2.1M LOC) increases maintenance surface. Single team ownership (decaporg org) means contributions depend on maintainer availability. Breaking changes possible during major version bumps, but mitigated by comprehensive test coverage and stale.yml automation for issue triage.

Active areas of work

Active development on backend integrations and editorial workflows—cypress tests show ongoing work on editorial_workflow with migrations, i18n support, and open authoring features. GitHub Actions workflows (create-release.yml, publish.yml) suggest recent package publishing. The .kodiak.toml auto-merge config indicates active PR flow.

Get running

git clone https://github.com/decaporg/decap-cms.git
cd decap-cms
npm install
npm run develop

Use Node.js version in .nvmrc (check with cat .nvmrc). Runs Nx-managed develop tasks in parallel across packages.

Daily commands: Development: npm run develop (starts all packages in parallel via Nx). Demo build: npm run build:demo. E2E tests locally: npm run test:e2e:dev (opens Cypress UI on http://localhost:8080). Full test suite: npm run test:all (lint + type-check + unit + e2e).

Map of the codebase

• packages/decap-cms/package.json — Main entry point and dependency manifest for the CMS package—defines all core dependencies and build scripts
• packages/decap-cms/src/index.ts — Primary export and initialization point for the Decap CMS library—all integrations start here
• .github/workflows/nodejs.yml — CI/CD pipeline defining test, lint, and build validation—must pass before any merge to main
• cypress.config.ts — E2E test configuration covering all backend integrations (GitHub, GitLab, Bitbucket)—critical for validating workflow stability
• babel.config.js — Transpilation and polyfill configuration—affects all package builds and runtime compatibility
• .eslintrc.js — Linting rules enforced across entire monorepo—all code contributions must satisfy these
• CONTRIBUTING.md — Development setup and contribution guidelines—required reading before first pull request

Components & responsibilities

• Backend Service Layer (JavaScript/TypeScript, REST) — Abstracts Git provider differences (GitHub GraphQL vs. GitLab REST vs. Bitbucket API); handles auth, file ops, and PR creation

How to make changes

Add Support for a New Git Backend Provider

1. Create a new package directory for the backend implementation (e.g., packages/decap-cms-backend-myservice/) (packages)
2. Implement the backend interface matching the GitHub/GitLab/Bitbucket pattern with auth, file read/write, and PR workflow methods (packages/decap-cms-backend-github-graphql/src)
3. Add corresponding E2E test suite following the pattern in cypress/e2e/ to validate editorial workflow and media operations (cypress/e2e/editorial_workflow_spec_myservice_backend.js)
4. Update the main package.json to include the new backend in build and test scripts (package.json)
5. Export the backend from packages/decap-cms/src/index.ts so it's accessible to users (packages/decap-cms/src/index.ts)

Add a New Field Widget Type

1. Create widget component in packages/decap-cms/src/components/Widgets/ following the pattern of existing widgets (e.g., StringWidget, MarkdownWidget) (packages/decap-cms/src/components/Widgets)
2. Register widget in the widget registry (typically in packages/decap-cms/src/lib/widgetRegistry.ts or similar) (packages/decap-cms/src)
3. Add Storybook story for the widget in .storybook directory to document behavior and variations (.storybook)
4. Add E2E test in cypress/e2e/ to validate widget rendering and field validation in the editor (cypress/e2e/field_validations_spec.js)

Add a New Editorial Workflow Feature

1. Implement feature logic in packages/decap-cms/src/reducers or packages/decap-cms/src/actions following Redux pattern (packages/decap-cms/src)
2. Add UI components in packages/decap-cms/src/components for the new workflow state or action (packages/decap-cms/src/components)
3. Add shared test scenario in cypress/e2e/common/editorial_workflow.js if applicable across backends (cypress/e2e/common/editorial_workflow.js)
4. Add backend-specific E2E tests in cypress/e2e/editorial_workflow_spec_*.js files to validate with each provider (cypress/e2e)

Why these technologies

• React + Redux — State management and UI framework enable complex editorial workflows with predictable data flow and time-travel debugging
• Nx Monorepo — Multiple independent backend packages (GitHub, GitLab, Bitbucket) with shared core—Nx provides efficient build caching and dependency resolution
• Cypress E2E Testing — Backend integrations must be validated against live Git providers; Cypress supports realistic user workflows and visual regression detection
• TypeScript — Type safety across monorepo reduces integration bugs; critical when backends have different API contracts
• GitHub Actions CI/CD — Tight integration with GitHub ecosystem for publishing; enables automated release management and status badge integration

Trade-offs already made

• Single-page app (SPA) architecture instead of server-rendered

  • Why: CMS must work with any static site generator and support offline editing; SPA maximizes compatibility and browser compatibility
  • Consequence: Larger initial bundle and reliance on client-side authentication; requires robust error handling for network failures

• Support multiple Git backends via pluggable interface instead of single provider

  • Why: Users have different Git hosting preferences; enables broader adoption across static site generator communities
  • Consequence: Increased testing matrix (6+ backends) and complex credential/API abstraction; each backend must implement full interface

• Comprehensive E2E test coverage over unit tests

  • Why: CMS value is in Git provider integration; unit tests insufficient to catch provider API changes or workflow bugs
  • Consequence: Slow CI pipeline (~30+ min) and complex test fixtures; requires real or mocked provider accounts

• Editorial workflow (draft/review/publish) as optional feature via config

  • Why: Different teams have different approval processes; simple workflow vs. editorial board approval
  • Consequence: Code duplication between workflow paths; harder to reason about state transitions

Non-goals (don't propose these)

• Real-time collaboration—single-user editing per entry
• Server-side rendering—fully client-side single-page app
• Authentication backend—relies on Git provider OAuth or Git credentials
• Media hosting—media stored in Git repository or third-party service, not CMS-owned
• Database—Git repository is the database; no persistent backend required

Traps & gotchas

Monorepo interdependencies: packages/ modules depend on each other; npm run clean && npm install may be needed after branch switches. Cypress fixtures: Some tests use HTTP_PROXY mocking (cypress/utils/mock-server)—ensure port 1080 is free or unset RECORD_FIXTURES. Node version: .nvmrc enforces a specific Node version; use nvm or volta to match or builds may fail silently. Git backend diversity: Test suite expects different Git APIs (GitHub REST/GraphQL, GitLab, Bitbucket); running all e2e tests requires auth tokens for each backend or tests skip. Build output splits: npm run build generates both ESM (build:esm) and UMD outputs; importing from wrong path breaks in some bundler configs.

Architecture

Concepts to learn

• Headless CMS — Decap CMS separates content management from presentation—understanding this pattern explains why it's backend-agnostic and returns JSON/YAML instead of HTML
• Git-based workflows (branching, commits, merges) — Core to Decap's architecture—all edits are Git commits, editorial workflow uses branches; understanding Git internals helps debug sync issues
• Editorial workflow (draft → review → publish) — Decap implements this via Git branches (cypress/e2e/common/editorial_workflow.js tests this extensively); critical feature for multi-user content teams
• Single-Page Application (SPA) state management — Decap CMS is a React SPA using Redux; understanding state containers and side effects (async auth, Git ops) is essential for debugging UI behavior
• OAuth 2.0 and Git provider authentication — All backends (GitHub, GitLab, Bitbucket) use OAuth; Decap handles token refresh and scoping—critical for understanding why certain operations fail with auth errors
• Monorepo with shared dependencies (Nx workspace) — Decap uses Nx to manage packages/ modules; understanding task graph and dependency isolation helps avoid build cascades and version conflicts
• Schema-driven UI generation — Decap's config.yml defines a schema, then the UI auto-generates fields (text, date, image, etc.); understanding this decoupling is core to how it stays backend-agnostic

Related repos

• netlify/netlify-cms — Direct predecessor; Decap CMS is the rebranded continuation with the same architecture
• forestryio/forestry.io — Alternative Git-backed headless CMS with similar UX targeting static site generators
• contentful/contentful.js — Competing headless CMS platform; useful for comparing API design and backend abstraction patterns
• decaporg/decap-website — Official documentation and marketing site for Decap CMS; shows real-world usage examples and guides
• getgrav/grav — Alternative flat-file CMS for static generators; different approach to the same problem (file-based, not Git-based)

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E test coverage for Proxy Git Backend with Large Media support

The repo has comprehensive E2E tests for most backends (GitHub, GitLab, Bitbucket with Large Media variants), but notably missing is coverage for the Proxy Git Backend with Large Media. Currently only editorial_workflow_spec_proxy_git_backend.js exists without a corresponding large media test. This is a high-value addition since Large Media is a critical feature that needs backend-agnostic validation.

• [ ] Create cypress/e2e/media_library_spec_proxy_git_backend_large_media.js following the pattern of media_library_spec_github_backend_rest.js and media_library_spec_git-gateway_github_backend_large_media.js
• [ ] Add test cases for uploading, transforming, and managing large media files through the Proxy Git Backend
• [ ] Update cypress/e2e/common/media_library.js shared utilities if needed to support Proxy backend specifics
• [ ] Add the new spec to CI workflows in .github/workflows/ (likely nodejs.yml or publish.yml)

Add unit tests for Open Authoring workflow edge cases

The repo has E2E tests for Open Authoring (editorial_workflow_spec_*_open_authoring.js), but lacks dedicated unit tests for the Open Authoring Redux reducers/actions. With Git-based editing and fork workflows being complex, adding unit test coverage for state management of Open Authoring would catch regressions early and improve code confidence.

• [ ] Identify Open Authoring Redux reducer/action files in packages/ (likely in state/auth or collections directories)
• [ ] Create corresponding *.test.ts or *.test.js files with test suites for: fork creation, pull request submission, fork synchronization, and permission handling
• [ ] Use existing test patterns from other reducer tests as reference (e.g., files in packages/decap-cms-core)
• [ ] Ensure tests run as part of npm run test:unit and achieve >80% branch coverage

Add GitHub Actions workflow for automated changelog and release notes generation

The repo has create-release.yml and publish.yml workflows, but no automated changelog generation from commits/PRs. With an active project using conventional commits (enforced via commitlint.config.js), automating changelog updates would reduce manual effort during releases and ensure consistent release note formatting.

• [ ] Create .github/workflows/changelog-update.yml that triggers on merged PRs with conventional commit messages
• [ ] Integrate a tool like auto-changelog or conventional-changelog to parse commits and update CHANGELOG.md
• [ ] Configure the workflow to automatically commit changelog updates back to the main branch or create a PR for review
• [ ] Update CONTRIBUTING.md to document the automated changelog process for contributors

Good first issues

• Add unit tests for packages/decap-cms-core/src/store slices that lack coverage—start with entry reducers (entries.ts) and add Jest tests in __tests__/entries.test.ts.
• Document the YAML schema validation step in README.md or add TypeScript types for config.yml structure—currently no JSDoc on the config loader in packages/decap-cms/src/.
• Improve Storybook stories for UI components in .storybook/main.js—many button/field components lack interactive examples, good for learning the component API.

Top contributors

• @martinjagodic — 37 commits
• @dependabot[bot] — 22 commits
• @yanthomasdev — 5 commits
• @demshy — 4 commits
• @EricGrill — 3 commits

Recent commits

• 9db5e1e — fix(richtext): invalid imports, rich text widget types, improve paste handling (#7803) (martinjagodic)
• 6ef2f9b — fix(core): return full entry object from invokeEvent instead of just data (#7667) (adbw-pge)
• 50986a0 — fix: adhere to remark's tokenizer rules #7315 (#7444) (fgnass)
• 708f6fa — Fix(#7442): dynamic loading of codemirror language modes (#7443) (fgnass)
• 02e3fe3 — chore(release): publish (martinjagodic)
• 78a94e9 — chore: add mdast-util-to-string to direct deps of decap-cms-widget-richtext (#7788) (fedetibaldo)
• 074354d — feat: allow special characters to pass through slugification (#6220) (mikestopcontinues)
• 69ce240 — chore(release): publish (martinjagodic)
• f9ea253 — fix: add decap-cms-widget-richtext dependency to package-lock (martinjagodic)
• be8cf6b — fix: add decap-cms-widget-richtext dependency (martinjagodic)

Security observations

The Decap CMS codebase shows moderate security posture. The project has a defined security policy and uses GitHub security features, but several areas require attention: (1) Security documentation is incomplete, (2) Dependency management strategy needs explicit audit procedures, (3) E2E tests handling sensitive credentials need clear guidelines, (4) CI/CD security scanning visibility is limited, (5) Configuration files critical to security are not reviewable from provided content. No critical hardcoded secrets or obvious injection vulnerabilities are apparent from the file structure alone, but credential handling in test fixtures and backend authentication flows should be audited. Strengths include: MIT licensing transparency, defined supported versions, and use of monorepo tooling which can improve security review. Recommendations: Complete security documentation, implement automated security scanning in CI/CD, establish clear credential handling policies, and conduct regular dependency audits.

• Medium · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file is truncated and does not provide complete vulnerability reporting instructions. The GitHub Security Advisories URL is incomplete (ends with '/ad' instead of full path), which may confuse users attempting to report security issues. Fix: Complete the SECURITY.md file with full vulnerability reporting instructions, proper GitHub Security Advisories link, and expected response timeframes for security reports.
• Medium · Outdated Dependency Management — package.json. The package.json shows no lock file strategy (package-lock.json or yarn.lock) visibility in the provided structure. Combined with monorepo structure using nx, there's potential for supply chain vulnerabilities if dependencies are not pinned and vetted. Fix: Ensure package-lock.json or yarn.lock is committed and regularly audited. Use 'npm audit' in CI/CD pipeline. Consider using tools like Dependabot for automated vulnerability scanning.
• Medium · E2E Test Credentials Exposure Risk — cypress/e2e/ (multiple test files), cypress.config.ts. Multiple E2E test files reference backend authentication (GitHub, GitLab, Bitbucket backends) but the codebase structure doesn't show clear secrets management. Test fixtures are recorded with HTTP_PROXY environment variable, indicating potential credential handling in test environments. Fix: Ensure test credentials are never committed to version control. Use environment variables for all sensitive data in tests. Implement pre-commit hooks to prevent credential leakage. Use tools like git-secrets or TruffleHog.
• Low · Missing CODEOWNERS Visibility — .github/CODEOWNERS. While CODEOWNERS file exists (.github/CODEOWNERS), its content is not provided. Without review, it's unclear if critical security-sensitive areas have appropriate reviewer coverage. Fix: Ensure CODEOWNERS includes security experts for sensitive areas: authentication modules, backend integrations, data serialization/deserialization logic, and API client code.
• Low · Build and Release Workflow Transparency — .github/workflows/ (all workflow files). GitHub workflow files exist (.github/workflows/) but content is not provided. Unable to verify if CI/CD pipelines include security checks, SAST scanning, and dependency auditing. Fix: Implement security scanning in CI/CD: Enable GitHub Security scanning features, integrate SAST tools (ESLint with security plugins), run npm audit, implement code signing for releases, and enforce branch protection rules.
• Low · NPM Configuration Not Reviewed — .npmrc. The .npmrc file exists but its contents are not provided. This file can contain registry configuration and authentication tokens if misconfigured. Fix: Ensure .npmrc does not contain hardcoded credentials. Use npm token management for CI/CD. Verify it's in .gitignore if sensitive. Use npm_config_* environment variables for authentication in CI/CD.
• Low · Git Attributes Configuration Not Reviewed — .gitattributes. The .gitattributes file exists but content is unavailable. This could affect how sensitive files are handled during version control operations. Fix: Review .gitattributes to ensure proper handling of sensitive files (credentials, keys). Use text/binary rules appropriately. Consider adding rules to prevent certain file types from being committed.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.