Backends

A backend defines where your content is stored and how Sveltia CMS interacts with it. Sveltia CMS primarily supports Git-based backends, allowing seamless integration with popular Git hosting services.

Supported Backends

Sveltia CMS supports the following Git-based backends:

• GitHub
• GitLab
• Gitea/Forgejo

For testing purposes, you can also use the Test Backend.

Some features only work with specific backends. For example, Editorial Workflow currently only works with the GitHub and GitLab backends.

Breaking changes from Netlify/Decap CMS

For performance reasons, Sveltia CMS does not support the Azure DevOps, Bitbucket and Git Gateway backends. Please note that Netlify has officially deprecated Git Gateway, along with Netlify Identity. If you’re using one of these backends with Netlify/Decap CMS, consider switching to GitHub, GitLab, Gitea or Forgejo before migrating to Sveltia CMS.

Also, Sveltia CMS does not support the undocumented custom backend API. The CMS.registerBackend method is a noop in Sveltia CMS. We may add support for custom backends in future releases, though compatibility with existing Netlify/Decap CMS custom backends is not guaranteed.

Configuration

All the configuration options for backends can be set in the backend option of your CMS configuration file. Here is a basic example of configuring the GitHub backend:

YAML

backend:
  name: github
  repo: user/repo

TOML

[backend]
name = "github"
repo = "user/repo"

JSON

{
  "backend": {
    "name": "github",
    "repo": "user/repo"
  }
}

JavaScript

{
  backend: {
    name: "github",
    repo: "user/repo",
  },
}

See the specific backend guides for detailed configuration instructions.

The following sections describe some common configuration options available for all Git-based backends.

Branch Selection

By default, Sveltia CMS interacts with the repository’s default branch (usually main or master). You can specify a different branch using the branch option in the backend configuration:

YAML

backend:
  name: github
  repo: user/repo
  branch: develop

TOML

[backend]
name = "github"
repo = "user/repo"
branch = "develop"

JSON

{
  "backend": {
    "name": "github",
    "repo": "user/repo",
    "branch": "develop"
  }
}

JavaScript

{
  backend: {
    name: "github",
    repo: "user/repo",
    branch: "develop",
  },
}

Authentication Methods

By default, Sveltia CMS allows users to sign in using either OAuth or an access token. You can restrict the available sign-in methods by setting the auth_methods option to an array containing only the methods you want to allow:

Value	Description
oauth	OAuth sign-in (e.g. “Sign In with GitHub”)
token	Access token sign-in

For example, to allow only OAuth sign-in and disable access token authentication:

YAML

backend:
  name: github
  repo: user/repo
  auth_methods: [oauth]

TOML

[backend]
name = "github"
repo = "user/repo"
auth_methods = ["oauth"]

JSON

{
  "backend": {
    "name": "github",
    "repo": "user/repo",
    "auth_methods": ["oauth"]
  }
}

JavaScript

{
  backend: {
    name: "github",
    repo: "user/repo",
    auth_methods: ["oauth"],
  },
}

To allow only access token sign-in and disable OAuth:

YAML

backend:
  name: github
  repo: user/repo
  auth_methods: [token]

TOML

[backend]
name = "github"
repo = "user/repo"
auth_methods = ["token"]

JSON

{
  "backend": {
    "name": "github",
    "repo": "user/repo",
    "auth_methods": ["token"]
  }
}

JavaScript

{
  backend: {
    name: "github",
    repo: "user/repo",
    auth_methods: ["token"],
  },
}

The auth_methods array must contain at least one method. An empty array will result in a configuration error.

Commit Messages

You can customize the Git commit messages used when saving content. The commit_messages option allows you to define templates for various actions. Here’s the default configuration:

YAML

backend:
  commit_messages:
    create: 'Create {{collection}} "{{slug}}"'
    update: 'Update {{collection}} "{{slug}}"'
    delete: 'Delete {{collection}} "{{slug}}"'
    uploadMedia: 'Upload "{{path}}"'
    deleteMedia: 'Delete "{{path}}"'
    openAuthoring: '{{message}}'

TOML

[backend.commit_messages]
create = "Create {{collection}} \"{{slug}}\""
update = "Update {{collection}} \"{{slug}}\""
delete = "Delete {{collection}} \"{{slug}}\""
uploadMedia = "Upload \"{{path}}\""
deleteMedia = "Delete \"{{path}}\""
openAuthoring = "{{message}}"

JSON

{
  "backend": {
    "commit_messages": {
      "create": "Create {{collection}} \"{{slug}}\"",
      "update": "Update {{collection}} \"{{slug}}\"",
      "delete": "Delete {{collection}} \"{{slug}}\"",
      "uploadMedia": "Upload \"{{path}}\"",
      "deleteMedia": "Delete \"{{path}}\"",
      "openAuthoring": "{{message}}"
    }
  }
}

JavaScript

{
  backend: {
    commit_messages: {
      create: 'Create {{collection}} "{{slug}}"',
      update: 'Update {{collection}} "{{slug}}"',
      delete: 'Delete {{collection}} "{{slug}}"',
      uploadMedia: 'Upload "{{path}}"',
      deleteMedia: 'Delete "{{path}}"',
      openAuthoring: '{{message}}',
    },
  },
}

The available commit types are:

• create, update, delete: Used when creating, updating, or deleting entries in collections.
• uploadMedia, deleteMedia: Used when uploading or deleting media assets.
• openAuthoring: Used when submitting changes via open authoring (fork and pull request).

TIP

Unlike most of other config options, the commit message keys are camelCased.

Available Template Tags

You can use the following template tags in commit messages:

• {{collection}}: The label_singular or label of the collection.
• {{slug}}: The slug of the entry.
• {{path}}: The file path of the media asset.
• {{message}}: The original commit message provided by the user.
• {{author-email}}: The email of the signed-in user, if available.
• {{author-login}}: The login name of the signed-in user, if available.
• {{author-name}}: The display name of the signed-in user, if available.

The following table summarizes which tags are supported for each commit type:

Commit Type	Supported Tags
create, update, delete	collection, slug, path, author-email, author-login, author-name
uploadMedia, deleteMedia	path, author-email, author-login, author-name
openAuthoring	message, author-email, author-login, author-name

Skipping CI/CD

It’s also possible to add the [skip ci] prefix to commit messages to prevent triggering CI/CD pipelines. See the deployments guide for more details.

Future Plans

We plan to add an option that prompts users to enter custom commit messages in the UI before saving changes.

Including Credentials in API Requests

By default, Sveltia CMS does not include cookies in API requests to the Git hosting service. If your self-hosted Git service instance requires authentication via cookies, you can set the include_credentials option to true:

YAML

backend:
  name: gitea
  repo: user/repo
  include_credentials: true

TOML

[backend]
name = "gitea"
repo = "user/repo"
include_credentials = true

JSON

{
  "backend": {
    "name": "gitea",
    "repo": "user/repo",
    "include_credentials": true
  }
}

JavaScript

{
  backend: {
    name: "gitea",
    repo: "user/repo",
    include_credentials: true,
  },
}

Your server must also set the Access-Control-Allow-Credentials header in API responses for this to work.