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, editors can easily manage content stored in GitHub repositories.

Requirements

• A GitHub account.
• A GitHub repository to store the content.
• Write access to the repository: the Write, Maintain or Admin role, whether granted directly or through an organization team. Users with read-only access can’t sign in, unless Open Authoring is enabled, which lets them work on a fork instead.
• Sveltia CMS installed in your project.

If the configured branch is protected and doesn’t allow a user to push, e.g. because it requires a pull request, collections using the Simple Workflow and the Asset Library are read-only for that user, as they commit to the branch directly. Collections using the Editorial Workflow still work, as they commit to branches of their own. GitHub doesn’t tell whether a user can merge a pull request, so the Publish button is still shown, and GitHub refuses the merge if the user isn’t allowed to make it.

CSP

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 Server instance, you need to set the api_root option in your backend configuration to point to your server’s API endpoint.

YAML

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

TOML

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

JSON

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

JavaScript

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

The API version for GitHub Enterprise is v3, so the REST API endpoint is https://HOSTNAME/api/v3. You can also set api_root to just https://HOSTNAME, in which case /api/v3 is appended automatically.

Sveltia CMS uses the GitHub GraphQL API where possible. Its endpoint is inferred from the api_root option by replacing the /api/v3 part with /api/graphql, e.g. https://github.example.com/api/graphql. If your server’s GraphQL endpoint is at a different URL, set it with the graphql_api_root option.

Don’t set the base_url option to your GitHub Enterprise Server URL. The base_url option specifies the URL of your OAuth client, not the GitHub instance. To sign in with the authorization code flow, deploy an OAuth client that supports GitHub Enterprise Server, such as Sveltia CMS Authenticator with the GITHUB_HOSTNAME environment variable, and point base_url to it. Alternatively, sign in with an access token.

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 authorization code flow 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 or updating the CMS configuration.

Just click the “Sign In with Token” button on the login screen. The prompt dialog will provide a link to the token generation page on GitHub with the required permissions pre-selected. Generate a new token and copy it to the clipboard, then paste it into the prompt dialog to log in. The token will be stored in the browser’s local storage and used for subsequent API requests.

If you create a fine-grained token yourself, give it access to the repository and the following repository permissions:

Permission	Access	Needed for
Contents	Read and write	Everything: reading and committing entries and assets
Pull requests	Read and write	The Editorial Workflow, which opens, labels, merges and closes a pull request for each entry

Metadata (read) is added automatically. A classic token needs the repo scope, which covers all of the above.

WARNING

With the Editorial Workflow, a token that has content access but no pull request access gets as far as committing the entry to its workflow branch, then fails with “Resource not accessible by personal access token” when the CMS tries to open the pull request. Edit the token to add the Pull requests permission; the branches already created will be reused the next time each entry is saved.

You can disable token authentication if needed.

PKCE Authorization

Unimplemented

We’re waiting for GitHub to support client-side PKCE authentication for single-page apps. It was planned for Q4 2025, but GitHub has put the project on hold. We can’t release this feature until GitHub provides this support. In the meantime, please use the 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.

There are multiple options for the OAuth client, including our own Sveltia CMS Authenticator, third-party OAuth clients made for Netlify/Decap CMS, or using Netlify as an OAuth provider.

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.

If the client serves the authorization page at a path other than /auth, also set the auth_endpoint option. If the client checks the site domain, you may need to set the site_domain option as well.

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.

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 your site is hosted on Netlify, you don’t need to install Sveltia CMS Authenticator or any other OAuth client. Instead, register a new OAuth app on GitHub and link it to your Netlify site. Here’s how:

1. Open the Register a new OAuth app page on GitHub. To create the app under an organization instead of your personal account, go to the organization’s Settings > Developer settings > OAuth Apps.
2. Fill in the Application name and Homepage URL with anything you like, such as your site name and URL.
3. Set the Authorization callback URL to https://api.netlify.com/auth/done.
4. Click Register application.
5. Copy the Client ID, then click Generate a new client secret and copy the Client Secret. The secret won’t be shown again.
6. Open the Netlify dashboard for your site and go to Project configuration > Security > OAuth. Note that this is not the Identity section, which is only used for Git Gateway and Netlify Identity.
7. Under Authentication Providers, click Install Provider, select GitHub, enter the Client ID and Client Secret, and save.

No configuration changes are needed in Sveltia CMS. Just make sure base_url is not set in your configuration file, so the CMS uses Netlify as the OAuth client. See Netlify’s official guide for more details.

Netlify identifies the site by its domain. If the CMS is served from a domain other than the one of your Netlify site, set the site_domain option.

Disclaimer

We are not affiliated with Netlify and do not endorse or maintain this authentication method. We only provide it to ensure backward compatibility with Netlify 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 the 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 Development 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.