GitHub Backend

GitHub is one of the most popular Git hosting services, and Sveltia CMS provides first-class support for it. With the GitHub backend, you can easily manage your content stored in GitHub repositories.

Requirements

• A GitHub account.
• A GitHub repository to store your content.
• Sveltia CMS installed in your project.

CSP Settings

If your site uses a Content Security Policy (CSP), You may need to update it to allow requests to GitHub. See the CSP documentation for more details.

Configuration

The base configuration for the GitHub backend is straightforward. You need to specify the name of the backend as github and provide the repo option with the format owner/repo, where owner is your GitHub username or organization name, and repo is the repository name.

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",
  },
}

GitHub Enterprise

By default, Sveltia CMS uses the public GitHub instance at https://github.com. If you use a self-hosted GitHub Enterprise instance, you need to set the base_url and api_root options in your backend configuration to point to your GitHub Enterprise server URL.

YAML

backend:
  name: github
  repo: owner/repo
  base_url: https://github.example.com
  api_root: https://github.example.com/api/v3

TOML

[backend]
name = "github"
repo = "owner/repo"
base_url = "https://github.example.com"
api_root = "https://github.example.com/api/v3"

JSON

{
  "backend": {
    "name": "github",
    "repo": "owner/repo",
    "base_url": "https://github.example.com",
    "api_root": "https://github.example.com/api/v3"
  }
}

JavaScript

{
  backend: {
    name: "github",
    repo: "owner/repo",
    base_url: "https://github.example.com",
    api_root: "https://github.example.com/api/v3",
  },
}

The API version for GitHub Enterprise is v3, so make sure to include /api/v3 in the api_root option.

Authentication

There are multiple ways to authenticate with GitHub when using Sveltia CMS. You can choose the method that best fits your needs. Using an access token is the simplest way to get started, but PKCE authorization is recommended if your CMS instance is used by multiple users or non-technical users because it’s more user-friendly and secure.

TIP

If you plan to only work with your local repository, you don’t need to set up authentication.

Access Token (Quick Start)

If you or a small team of developers are the only users of your CMS instance, you can use a personal access token (PAT) for authentication. This method is straightforward and doesn’t require setting up an OAuth app.

Just click the “Sign In with Token” button on the login screen and enter your token. The prompt dialog will provide a link to the token generation page on GitHub with the required scopes pre-selected.

PKCE Authorization

Coming Soon

This method becomes available once GitHub releases client-side PKCE support. It was planned for Q4 2025 but there’s no official release date yet. Check back later for updates. Until then, please use other authentication methods described in this document.

Authorization Code Flow

The authorization code flow requires you to set up an OAuth app on GitHub and deploy an OAuth client server to handle the authentication process. Here are the steps to set it up:

Using Netlify

For backward compatibility with Netlify CMS, Sveltia CMS supports the authorization code flow using Netlify as an OAuth client. It’s the default authentication method if you don’t configure authentication explicitly, and you don’t need to set up a backend server yourself.

If you’re a Netlify customer, follow the official guide to register a new OAuth app on GitHub and link it to your Netlify site. No configuration changes are needed in Sveltia CMS.

Using Sveltia CMS Authenticator

We provide our own OAuth client called Sveltia CMS Authenticator that you can deploy on Cloudflare Workers. Follow the instructions in the repository to deploy the authenticator and update your CMS configuration file to include the base_url option pointing to your authenticator URL:

YAML

backend:
  name: github
  repo: owner/repo
  base_url: YOUR_CLIENT_URL # URL of your OAuth client

TOML

[backend]
name = "github"
repo = "owner/repo"
base_url = "YOUR_CLIENT_URL"

JSON

{
  "backend": {
    "name": "github",
    "repo": "owner/repo",
    "base_url": "YOUR_CLIENT_URL"
  }
}

JavaScript

{
  backend: {
    name: "github",
    repo: "owner/repo",
    base_url: "YOUR_CLIENT_URL",
  },
}

Using Third-Party OAuth Client

You can also use third-party OAuth clients made for Netlify/Decap CMS. These clients support various languages and hosting services, and they should work with Sveltia CMS as well without any modifications.

The setup process is similar to using Sveltia CMS Authenticator. You need to register a new OAuth app on GitHub and configure the third-party client with the app credentials. Then, update your CMS configuration to include the base_url option pointing to your OAuth client URL, like in the example above.

Disclaimer

Third-party clients are not reviewed or maintained by the Sveltia CMS team. Use them at your own risk. Some clients may not be compatible with Sveltia CMS.

Features

Git LFS

Git Large File Storage (LFS) is not supported in the GitHub backend at this time due to the API limitations. We plan to explore possible solutions in the future.

GraphQL

GraphQL support is enabled for GitHub repositories. Sveltia CMS uses the GitHub GraphQL API to interact with the repository, which provides better performance and flexibility compared to the REST API. No additional configuration is needed to enable GraphQL support.

Commit Signing

When you commit changes to your GitHub repository through Sveltia CMS, the commits are automatically GPG-signed and marked as verified. This ensures the authenticity and integrity of your commits, providing an additional layer of security for your content management workflow. No additional configuration is needed to enable commit signing.

Service Status Checking

Service status checking is available for GitHub repositories, unless you’re using a GitHub Enterprise instance. Sveltia CMS periodically checks the status of the GitHub service to ensure that it is operational. If any incidents are detected, a notification banner will be displayed in the CMS UI to inform users of potential issues that may affect their workflow.

Workflows

The following content management workflows are supported with the GitHub backend:

• Local Workflow
• Simple Workflow
• Editorial Workflow
• Open Authoring

Deployment

GitHub Actions is a great choice for deploying Sveltia CMS sites hosted on GitHub. GitHub Pages is free for public repositories and easy to set up.

There are also other deployment options, including Cloudflare Pages, Netlify, and Vercel. They provide seamless integration with GitHub repositories and support automatic deployments on push, with additional benefits like serverless functions, storage and AI integrations.

Choose the deployment platform that best fits your needs and follow their documentation to set up continuous deployment for your Sveltia CMS site.