--- url: /en/docs/backends/github.md description: >- Configure GitHub backend in Sveltia CMS for managing content in GitHub repositories. --- # 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](/en/docs/workflows/open) is enabled, which lets them work on a fork instead. * Sveltia CMS installed in your project. If the configured branch is [protected](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) and doesn’t allow a user to push, e.g. because it requires a pull request, collections using the [Simple Workflow](/en/docs/workflows/simple) and the [Asset Library](/en/docs/ui/asset-library) are read-only for that user, as they commit to the branch directly. Collections using the [Editorial Workflow](/en/docs/workflows/editorial) 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](/en/docs/security#setting-up-content-security-policy) 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. ::: code-group ```yaml [YAML] backend: name: github repo: user/repo ``` ```toml [TOML] [backend] name = "github" repo = "user/repo" ``` ```json [JSON] { "backend": { "name": "github", "repo": "user/repo" } } ``` ```js [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. ::: code-group ```yaml [YAML]{4} backend: name: github repo: owner/repo api_root: https://github.example.com/api/v3 ``` ```toml [TOML]{4} [backend] name = "github" repo = "owner/repo" api_root = "https://github.example.com/api/v3" ``` ```json [JSON]{5} { "backend": { "name": "github", "repo": "owner/repo", "api_root": "https://github.example.com/api/v3" } } ``` ```js [JavaScript]{5} { 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](#authorization-code-flow), deploy an OAuth client that supports GitHub Enterprise Server, such as [Sveltia CMS Authenticator](https://github.com/sveltia/sveltia-cms-auth) with the `GITHUB_HOSTNAME` environment variable, and point `base_url` to it. Alternatively, sign in with an [access token](#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](/en/docs/workflows/local), you don’t need to set up authentication. ::: ### Access Token (Quick Start) {#access-token} If you or a small team of developers are the only users of your CMS instance, you can use a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) (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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-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](/en/docs/workflows/editorial), 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](/en/docs/backends#authentication-methods) if needed. ### PKCE Authorization ::: warning Unimplemented We’re waiting for GitHub to support client-side PKCE authentication for single-page apps. It was [planned for Q4 2025](https://github.com/github/roadmap/issues/1153), but GitHub has [put the project on hold](https://github.com/orgs/community/discussions/15752). 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](https://github.com/sveltia/sveltia-cms-auth) 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: ::: code-group ```yaml [YAML]{4} backend: name: github repo: owner/repo base_url: YOUR_CLIENT_URL # URL of your OAuth client ``` ```toml [TOML]{4} [backend] name = "github" repo = "owner/repo" base_url = "YOUR_CLIENT_URL" ``` ```json [JSON]{5} { "backend": { "name": "github", "repo": "owner/repo", "base_url": "YOUR_CLIENT_URL" } } ``` ```js [JavaScript]{5} { backend: { name: "github", repo: "owner/repo", base_url: "YOUR_CLIENT_URL", }, } ``` ::: #### Using Third-Party OAuth Client You can also use [third-party OAuth clients](https://decapcms.org/docs/external-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`](/en/docs/backends#oauth-endpoint) option. If the client checks the site domain, you may need to set the [`site_domain`](/en/docs/backends#site-domain) option as well. ::: info 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](https://github.com/settings/applications/new) 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](https://docs.netlify.com/manage/security/secure-access-to-sites/oauth-provider-tokens/) 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`](/en/docs/backends#site-domain) option. ::: info 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](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). 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](https://www.githubstatus.com/) 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](/en/docs/workflows) are supported with the GitHub backend: * [Local Development Workflow](/en/docs/workflows/local) * [Simple Workflow](/en/docs/workflows/simple) * [Editorial Workflow](/en/docs/workflows/editorial) * [Open Authoring](/en/docs/workflows/open) ## Deployment [GitHub Actions](https://github.com/features/actions) is a great choice for deploying Sveltia CMS sites hosted on GitHub. [GitHub Pages](https://docs.github.com/en/pages) is free for public repositories and easy to set up. There are also other deployment options, including [Cloudflare Pages](https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/), [Netlify](https://www.netlify.com/integrations/github/), and [Vercel](https://vercel.com/docs/git/vercel-for-github). 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.