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
Section titled “Local Storage”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.
cms({ storage: { type: "local" },});GitHub Storage
Section titled “GitHub Storage”cms({ storage: { type: "github", repo: "owner/repo", branch: "main", clientId: "your-github-app-client-id", publishMode: "pull-request", },});Configuration
Section titled “Configuration”| 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 |
Setting up the GitHub App
Section titled “Setting up the GitHub App”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.
- Go to Settings > Developer Settings > GitHub Apps and create a new app.
- Under Permissions, grant Repository permissions → Contents: Read and write and Pull requests: Read and write. Nothing else is needed.
- Set Callback URL to
https://your-site.example/_astronaut-cms/api/callback. Under a sitebase, include it:https://your-site.example/docs/_astronaut-cms/api/callback. WithtrailingSlash: "always", end it with a slash, since the routes only answer in that form. The integration logs the exact URL on startup. - Enable Expire user authorization tokens. The CMS refreshes them on its own, so editors never notice.
- Install the app on the content repository.
- Copy the Client ID into
clientId, generate a Client secret, and set it asASTRONAUT_CMS_GITHUB_CLIENT_SECRETon the server.
GitLab Storage
Section titled “GitLab Storage”The GitLab backend uses the GitLab API and supports self-hosted instances.
cms({ storage: { type: "gitlab", project: "group/project", branch: "main", clientId: "your-gitlab-application-id", instanceUrl: "https://gitlab.com", publishMode: "pull-request", },});Configuration
Section titled “Configuration”| 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 |
Setting up the GitLab application
Section titled “Setting up the GitLab application”- Go to User Settings > Applications (or Admin > Applications for instance-wide).
- Create a confidential application with the
apiscope. - Set the redirect URI to
https://your-site.example/_astronaut-cms/api/callback, with a trailing slash undertrailingSlash: "always"(the integration logs the exact URL on startup). - Copy the Application ID into
clientIdand set the Secret asASTRONAUT_CMS_GITLAB_CLIENT_SECRETon the server.
What the server needs
Section titled “What the server needs”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.
How signing in works
Section titled “How signing in works”- The editor opens the admin panel. The browser asks the server whether it has a session.
- If not, they click sign in and the browser navigates to
/_astronaut-cms/api/login, which redirects to the provider. - The provider sends them back to
/_astronaut-cms/api/callbackwith a code. The server redeems it, checks that they may write to the configured repository, and sets an encryptedHttpOnlycookie. - 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.
Publish Modes
Section titled “Publish Modes”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.
Access proxies
Section titled “Access proxies”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.
Expired proxy sessions
Section titled “Expired proxy sessions”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.
