Contributions are always welcome, no matter how large or small. Before contributing, please read the code of conduct.
For details on contributing to documentation, see Website Readme.
Install Node.js (LTS) and pnpm on your system.
git clone https://github.com/decaporg/decap-cms
cd decap-cms
pnpm installpnpm run startRemoves all of the CMS package dist directories.
pnpm run cleanRuns the clean script and removes all the node_modules from the CMS packages.
pnpm run resetRuns the clean script and builds the CMS packages.
pnpm run buildRuns the build and build-preview scripts in each package and serves the resulting build locally.
pnpm run build-previewRuns linting and Jest tests.
pnpm run testRuns linting, Jest, and Cypress tests.
pnpm run test:allRuns Cypress e2e tests.
pnpm run test:e2eRuns Cypress e2e tests on watch mode with an open instance of Chrome.
pnpm run test:e2e:devFormats code and docs according to our style guidelines.
pnpm run formatWe actively welcome your pull requests!
If you need help with Git or our workflow, please ask in our community chat. We want your contributions even if you're just learning Git. Our maintainers are happy to help!
Decap CMS uses the Forking Workflow + Feature Branches. Additionally, PR's should be rebased on main when opened, and again before merging.
- Fork the repo.
- Create a branch from
main. If you're addressing a specific issue, prefix your branch name with the issue number. - If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Run
pnpm run testand ensure the test suite passes. - Use
pnpm run formatto format and lint your code. - PR's must be rebased before merge (feel free to ask for help).
- PR should be reviewed by two maintainers prior to merging.
pnpm run start spawns a development server and uses dev-test/config.yml and dev-test/index.html to serve the CMS.
In order to debug a specific issue follow the next steps:
- Replace
dev-test/config.ymlwith the relevantconfig.yml. If you want to test the backend, make sure that thebackendproperty of the config indicates which backend you use (GitHub, Gitlab, Bitbucket etc) and path to the repo.
backend:
name: github
repo: owner-name/repo-name- Change the content of
dev-test/index.htmlto:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Decap CMS</title>
</head>
<body>
<script src="dist/decap-cms.js"></script>
<!-- <script>
// this is the place to add CMS customizations if you need to, e.g.
CMS.registerPreviewTemplate('posts', PostPreview);
</script> -->
</body>
</html>The most important thing is to make sure that Decap CMS is loaded from the dist folder. This way, every time you make changes to the source code, they will be compiled and reflected immediately on localhost.
- Run
pnpm run start - Open
http://localhost:8080/in the browser and you should have access to the CMS
When debugging the CMS with Git Gateway you must:
-
Have a Netlify site with Git Gateway and Netlify Identity enabled. An easy way to create such a site is to use a template, for example the Gatsby template
-
Tell the CMS the URL of your Netlify site using a local storage item. To do so:
- Open
http://localhost:8080/in the browser - Open the Developer Console. Write the below command and press enter:
localStorage.setItem('netlifySiteURL', 'https://yourwebsiteurl.netlify.app/') - To be sure, you can run this command as well:
localStorage.getItem('netlifySiteURL') - Refresh the page
- You should be able to log in via your Netlify Identity email/password
- Open
Same steps as above, with a Turbo-specific dev-test/config.yml:
backend:
name: turbo-github
turbo_site_id: <a develop site's site id>
turbo_config_url: https://ioltadnfuvnndhbzbagl.supabase.co/functions/v1/config
turbo_admin_url: https://develop--decap-turbo.netlify.appUse a site on the develop Supabase project, not production. Before logging in, add http://localhost:8080 to that site's admin interface URLs in the Turbo dashboard, or the login popup will refuse the origin.
There are situations where you would want to run a specific test file, or tests that match a certain pattern.
To run all the tests for a specific file, use this command:
npx jest <filename or file path>
The first part of the command, npx jest means running the locally installed version of jest. It is equivalent to running node_modules/.bin/jest.
Example for running all the tests for the file gitlab.spec.js: npx jest gitlab.spec.js
Some test files like API.spec.js is available in several packages. You can pass a regexp pattern instead of file path to narrow down files.
Example for running all the tests for the file API.spec.js in the decap-cms-backend-gitlab package:
npx jest ".+backend-gitlab/.+/API.spec.js
To run a specific test in a file, add the flag --testNamePattern, or -t for short followed by a regexp to match your test name.
Example for running the test "should return true on project access_level >= 30" in the API.spec.js in decap-cms-backend-gitlab package:
npx jest -t "true on p" ".+backend-gitlab/.+/API.spec.js"
For more information about running tests exactly the way you want, check out the official documentation for Jest CLI.
Decap CMS uses NPM trusted publishers with OIDC for secure, automated package publishing.
- Publishing is automated via GitHub Actions when version tags are pushed
- Uses OpenID Connect (OIDC) for authentication. No NPM tokens required
- Each package has a trusted publisher configured on npmjs.com
- Workflow generates short-lived, cryptographically-signed tokens automatically
- Lerna bumps versions and tags;
pnpm publish -rdoes the publishing
Important
Never run lerna publish (in any form, including from-git and from-package).
Package manifests declare their dependencies as catalog:, a pnpm-workspace-internal protocol that has to be substituted with the real semver ranges at publish time. pnpm publish does that substitution; Lerna's publish client does not, and uploads the literal string catalog: to the registry. The result installs fine with pnpm inside this workspace and is broken for every consumer using npm, yarn or bun.
This is what happened in the 2026-09-08 release: eight packages, including decap-server@3.11.1, shipped uninstallable. See #7979.
Use lerna version to bump and tag. Publishing is CI's job, and pnpm run publish:packages is the only manual fallback.
- Prepare the release:
# Ensure your local `main` branch is up to date
pnpm install --frozen-lockfile
pnpm run test
# Bump versions for changed packages
pnpm exec lerna version
# This will:
# - Detect changed packages since last release
# - Bump versions according to conventional commits
# - Update CHANGELOG.md
# - Create git commit and tags
# - Push to upstream-
Publish:
- Run the Publish Packages workflow manually from the Actions tab, against the
chore(release): publishcommit - Leave dist-tag on
latestfor a normal release; set it tobetafor a prerelease - GitHub Actions runs tests and builds packages
scripts/publish-packages.mjspublishes to npm using OIDC, skipping versions already on the registry- Provenance attestations are generated automatically
- Every published manifest is verified afterwards, whether or not the publish succeeded
[!NOTE] The workflow also has a tag trigger, but do not rely on it for a release. GitHub creates no workflow run at all when a single push carries many tags, and a release pushes one tag per package. Use the manual trigger.
[!NOTE] Re-running the workflow against a partially published release is safe and is the intended way to resume one. The publish script asks the registry what already exists and never re-uploads it, so a second run picks up exactly what is left.
[!WARNING] Never pass publish flags through
pnpm run.pnpm run <script> -- --flaginjects a literal--, so the flags arrive as positional arguments and are dropped without a word:pnpm run publish:packages -- --tag beta --dry-runignores both and publishes for real, tolatest. Invoke the script orpnpm publishdirectly. - Run the Publish Packages workflow manually from the Actions tab, against the
-
Verify the release:
git pull pnpm run verify:published
The publish workflow runs this too, but run it locally as well after any release that needed manual intervention. It fetches every publishable package from the registry at the version in your working tree and fails if a published manifest still contains
catalog:orworkspace:specifiers.npm accepts a publish before the version becomes readable, so the check allows up to 10 minutes for absent versions to appear before failing. Unresolved specifiers fail immediately -- that is a property of the published manifest and will not change on its own.
-
Create GitHub release:
- Go to Releases
- Draft a new release from the tag
- Add release notes highlighting changes
A prerelease must never land on the latest dist-tag. npm does not infer a tag from the version, so 3.20.0-beta.0 published without --tag becomes what npm install decap-cms resolves to.
# From a release/* branch -- lerna.json's allowBranch permits main and release/*
pnpm exec lerna version --conventional-prerelease --preid betaThen run Publish Packages against the resulting chore(release): publish commit with dist-tag set to beta, and confirm both tags afterwards:
npm view decap-cms dist-tags # latest unchanged; beta on the new versionRepeating lerna version --conventional-prerelease --preid beta bumps -beta.0 to -beta.1. Note that a prerelease is all-or-nothing: every package is versioned together and the beta manifests pin each other at exact beta versions, so consumers have to take the whole set from beta.
npm configures trusted publishing per existing package, so there is nothing for CI to exchange an OIDC token against until a package's first version exists. CI cannot create a package. Publish the first version from a maintainer machine, then configure trusted publishing for it on npmjs.com:
npm login
pnpm publish --filter <package-name> --no-git-checks --tag beta --access publicUse pnpm, never npm publish, which does not understand catalog: and would ship the specifier literally. The publish script detects this case and prints the exact command for the packages that need it.
If automated publishing fails and you need to publish manually:
# Authenticate with npm (uses session-based auth with 2FA)
npm login
# Publish changed packages -- pnpm, never lerna, see the warning above
pnpm run publish:packages
# Always confirm what actually reached the registry
pnpm run verify:publishedNote: Manual publishing still requires 2FA. Use recovery codes if you don't have access to your 2FA device.
pnpm publish -r skips versions that are already on the registry, so it is safe to re-run against a partially published release.
By contributing to Decap CMS, you agree that your contributions will be licensed under its MIT license.