Skip to content

Storage Backends

Astronaut CMS supports three storage backends. During development you use local storage, and in production you connect to GitHub or GitLab.

Whichever you pick, the browser never talks to the Git provider. The admin panel calls your own site, and the server holds the repository session and makes every provider call. That is what the Security Model is built on, and it is why a production deployment needs an SSR adapter.

Local storage is the default. It reads and writes files directly in the working tree. Its pending changes are what the working tree holds beyond the git index, within the collections and media directories. Whatever you stage with git add is yours: the admin neither lists it nor discards it, so staging is how you keep a hand edit out of the admin’s changeset.

astro.config.ts
cms({
storage: { type: "local" },
});
astro.config.ts
cms({
storage: {
type: "github",
repo: "owner/repo",
branch: "main",
clientId: "your-github-app-client-id",
publishMode: "pull-request",
},
});
Option Type Default Description
repo string required GitHub repository in owner/repo format
branch string "main" Target branch for reading and writing
clientId string required GitHub App client ID
publishMode "direct" | "pull-request" "direct" How changes are published

A GitHub App is the only GitHub authentication the CMS accepts. A classic OAuth App issues a coarse token that covers every repository the editor can reach and never expires, which is a poor thing for a deployment to hold on an editor’s behalf. A GitHub App issues a token limited to the installation that expires in hours and refreshes itself.

  1. Go to Settings > Developer Settings > GitHub Apps and create a new app.
  2. Under Permissions, grant Repository permissions → Contents: Read and write and Pull requests: Read and write. Nothing else is needed.
  3. Set Callback URL to https://your-site.example/_astronaut-cms/api/callback. Under a site base, include it: https://your-site.example/docs/_astronaut-cms/api/callback. With trailingSlash: "always", end it with a slash, since the routes only answer in that form. The integration logs the exact URL on startup.
  4. Enable Expire user authorization tokens. The CMS refreshes them on its own, so editors never notice.
  5. Install the app on the content repository.
  6. Copy the Client ID into clientId, generate a Client secret, and set it as ASTRONAUT_CMS_GITHUB_CLIENT_SECRET on the server.

The GitLab backend uses the GitLab API and supports self-hosted instances.

astro.config.ts
cms({
storage: {
type: "gitlab",
project: "group/project",
branch: "main",
clientId: "your-gitlab-application-id",
instanceUrl: "https://gitlab.com",
publishMode: "pull-request",
},
});
Option Type Default Description
project string required GitLab project in group/project format
branch string "main" Target branch
clientId string required GitLab application ID
instanceUrl string "https://gitlab.com" GitLab instance URL for self-hosted instances
scopes string[] ["api"] OAuth scopes
publishMode "direct" | "pull-request" "direct" How changes are published
  1. Go to User Settings > Applications (or Admin > Applications for instance-wide).
  2. Create a confidential application with the api scope.
  3. Set the redirect URI to https://your-site.example/_astronaut-cms/api/callback, with a trailing slash under trailingSlash: "always" (the integration logs the exact URL on startup).
  4. Copy the Application ID into clientId and set the Secret as ASTRONAUT_CMS_GITLAB_CLIENT_SECRET on the server.

One secret, the one your OAuth app already gave you:

Variable Purpose
ASTRONAUT_CMS_GITHUB_CLIENT_SECRET GitHub App client secret, for redeeming the authorization code.
ASTRONAUT_CMS_GITLAB_CLIENT_SECRET The same, for GitLab.

The integration declares these through astro:env, so Astro validates and types them without an env.schema entry of yours. Every secret is optional, so a build with env.validateSecrets passes without it, as it must where the host provides secrets only at runtime (Workers secrets, Netlify and Vercel environment variables). Sign-in reports a missing one when it needs it.

The session cookie’s key is derived from it, so there is nothing else to generate or seed. See Where the cookie key comes from.

You also need an SSR adapter (@astrojs/node, @astrojs/cloudflare, @astrojs/vercel, @astrojs/netlify, …). The CMS holds the repository session on the server, so its API routes render on demand; the build fails with a message saying so if no adapter is registered. To build a purely static site without the admin, for example for a deployment nobody edits, set admin: false and drop the adapter.

  1. The editor opens the admin panel. The browser asks the server whether it has a session.
  2. If not, they click sign in and the browser navigates to /_astronaut-cms/api/login, which redirects to the provider.
  3. The provider sends them back to /_astronaut-cms/api/callback with a code. The server redeems it, checks that they may write to the configured repository, and sets an encrypted HttpOnly cookie.
  4. Every later call carries that cookie. The token inside it never reaches the browser.

The state parameter travels in its own short-lived encrypted cookie rather than in sessionStorage, so script in the admin can neither read it nor plant one.

Both GitHub and GitLab backends support two publish modes:

  • "direct" — Changes are committed to the editor’s draft branch and merged into the configured branch when they publish.
  • "pull-request" / "merge-request" — Publishing opens a pull/merge request for review instead of merging.

Either way the draft branch (cms/<username>) is the changeset: everything on it is pending, and publish and discard act on all of it at once.

An access proxy sits in front of the whole site and demands a sign-in before any request reaches it: Cloudflare Access, Vercel’s Deployment Protection, or Netlify’s password and SSO protection. Putting one in front of the admin panel is worth doing: it keeps unauthenticated traffic away from /admin entirely, and the admin bundle with it.

The editor still signs in twice, but barely

Section titled “The editor still signs in twice, but barely”

Pointing the proxy at the same identity provider the CMS uses does not remove the CMS’s own sign-in, and no configuration can make it. The two prove different things:

  • The proxy establishes identity. It runs its own OAuth exchange, consumes the resulting token itself, and issues a session cookie for your hostname. The provider’s token never reaches the application: Cloudflare passes through custom OIDC claims, Vercel Passport a signed JWT of claims, neither the upstream access token.
  • The CMS needs a capability: a repository-scoped token it uses against the Git provider’s API. Only a grant the editor makes to the CMS’s own app produces one.

Behind Cloudflare Access the CMS makes the second one invisible. Access sets a Cf-Access-Jwt-Assertion header on every request it lets through, and when the CMS sees it with no session of its own it starts the provider redirect immediately instead of showing a sign-in button. The editor has a live provider session from moments earlier, so the provider approves without prompting and returns them to the admin panel. This needs no configuration at all.

When a proxy session lapses mid-edit, the proxy answers requests with a redirect to its own login origin, which a browser can only surface as an opaque network failure. The CMS detects it and says so, asking for a page reload, which is the only thing that can complete the proxy’s sign-in. To make it rare, set the proxy’s session lifetime longer than the CMS session’s.