CMS Setup & GitHub OAuth

Because Sveltia CMS operates entirely as a static single-page application (SPA) inside the browser, it requires a secure authentication bridge to interact with GitHub’s API. This connection is established using GitHub OAuth, ensuring that subject matter experts can safely log in, edit content, and generate pull requests using their own credentials.

---

Architecture of Authentication

The authentication flow relies on a secure token exchange between the browser CMS client and GitHub:

1. Login Trigger The user navigates to /admin/ and clicks Login with GitHub.
   1. OAuth Handshake The browser redirects to GitHub’s authorization page, prompting the user to grant repository access permissions.
   2. Token Issuance Upon approval, GitHub returns an OAuth access token back to the authentication gateway.
   3. API Communication Sveltia CMS uses this token to fetch files, commit changes, and open pull requests directly on behalf of the authenticated user.

---

Configuring the GitHub OAuth App

To enable authentication for your repository, you must register an OAuth application within your GitHub organization or personal account settings:

1. Register Application

Navigate to GitHub Settings > Developer Settings > OAuth Apps > New OAuth App.

• Application Name: Sveltia Docs CMS (Local/Production)
• Homepage URL: https://docs.timothyjohnsonwrites.com (or http://localhost:4321 for local testing)
• Authorization Callback URL: https://api.netlify.com/auth/done (or your chosen OAuth gateway provider URL)

2. Environment Variables

Securing your Client ID and Client Secret.

Your deployment host (such as Netlify, Vercel, or a custom OAuth server) requires two environment variables to handle the handshake securely:

OAUTH_CLIENT_ID=your_github_oauth_client_id
OAUTH_CLIENT_SECRET=your_github_oauth_client_secret

---

Connecting config.yml to the Backend

The final step is defining the backend authentication provider inside your CMS configuration file (public/admin/config.yml):

backend:
  name: github
  repo: write-tim/sveltia-docs-test
  branch: main
  base_url: [https://your-oauth-gateway-provider.com](https://your-oauth-gateway-provider.com)
  auth_endpoint: auth