docs menu

Sites and code

Galerne can host the website of a project. It keeps the code in a git repo on Galerne's own Forgejo server, in the EU, and builds and serves it on Tramontane, the EU frontend cloud. You never need a git account: agents change the code through MCP, people review and promote it in the studio. The code stays yours: clone it any time, or mirror it to your own GitHub or GitLab.

A project can also stay headless only. Then nothing here applies, and your site reads Galerne from wherever it runs (Next.js).

Create the site#

In the studio, Settings, Site, an admin chooses create site. Agents with an admin token call create_site. Galerne then:

  1. creates a private repo from a site template, with main open to the platform only;
  2. creates the site on Tramontane, in the Tramontane team of the person creating it (accounts are shared by email);
  3. sets the site's environment: the API URL, the project, a token for published reads, the preview secrets and draft tokens of production and of branch builds, and the webhook secret;
  4. adds a webhook so publishing purges the site's cache, and starts the first build.

There are two templates. starter brings its own sample model (pages, posts, people and 16 blocks) and fits a new project. bare fits a project that already has its content types, imported from another CMS or modelled before: it starts from the project's deployed schema and renders every routed doc, and agents build the blocks for that model. create_site takes template; without it, Galerne picks bare when the deployed schema has types the starter does not define.

The repo also holds the Galerne packages the site uses, such as the Next.js kit, under galerne/, with the Galerne version in galerne/VERSION: the site builds from its own repo alone.

Running create_site again keeps what is already done, so a stopped attempt finishes on the next call. Once the first build gives the site its URL, refresh stores it.

One branch for code and content#

A branch has the same name in git and in the content: agent/new-hero holds the code change and the content change that go with it.

  • Writing code on a new branch opens the content branch of the same name, and so does a branch pushed with git.
  • Each code branch gets its own preview on Tramontane. Opened through a preview link, it shows the drafts of its content branch; other visitors see published content. The doc editor and the design tab show that build when you work on the branch, and the production site in draft mode on branches without code changes.
  • request_code_review asks for one review of both. Reviewers see the code changes in the note and the content changes in the studio.
  • When the code changes galerne.config.ts, deploy it on the branch with deploy_schema and branch (or galerne schema deploy --branch <name>). Content on the branch can then use the new types and fields, and main keeps its schema until promotion. Nothing deploys it on its own when the file changes.
  • Promoting the branch in the studio checks that its code merges into main, deploys the branch's schema, promotes the content, then merges the code. Tramontane rebuilds production.

Agents write on their own branches, as for content. Writing code on main needs the right to write on main, and main changes through promotion otherwise.

Tools for agents#

ToolRightWhat it does
create_siteadminCreates the repo, the hosted site, its environment and the webhook
refresh_siteadminStores the site URL, wires the webhook, gives the site the current preview secrets again; rebuild builds production again
list_filesreadFiles of a branch, under a folder if given
read_filereadOne file: text as UTF-8, others as base64, up to 1 MB
write_fileswrite on the branchCreates, updates or deletes up to 200 files in one commit
code_branchesreadBranches with their last commit, content branch and preview
code_changesreadCommits and files a branch changes compared to main
build_statusreadLatest builds, for one branch or all
build_logsreadLog lines of a build, page by page
preview_urlreadWhere to see a branch, and the link that opens it in draft mode
delete_siteadmin, people onlyDeletes the hosted site, the repo, git access, the site's tokens and webhook; content stays
update_site_settingsadminPublic URL, routes per type, preview URL, llms.txt
site_envadminA .env.local for running the site locally, with a new read token
request_code_reviewrequest reviewAsks for a review of the branch's code and content
promote_codepromoteMerges a code branch into main; dryRun only checks it
update_themewrite on the branchChanges design tokens in theme/tokens.json in one commit
set_mirror, list_mirrorsadmin, readMirrors the repo to your GitHub or GitLab
git_accesswriteA token for plain git, valid 30 days

The tool reference lists every input. Over HTTP, the same tools answer at POST /p/<project>/v1/tools/<name>.

write_files refuses paths outside the repo, anything under .git, and secrets files such as .env or private keys: the site gets its secrets from its environment. Files are 1 MB at most, 8 MB per commit. Files that did not change are left out of the commit.

json
{
  "branch": "agent/new-hero",
  "message": "Add a hero block",
  "files": [
    { "path": "app/blocks/hero.tsx", "content": "export function Hero() { … }" },
    { "path": "public/hero.png", "content": "iVBORw0KGgo…", "encoding": "base64" },
    { "path": "app/blocks/old-banner.tsx", "delete": true }
  ]
}

Plain git#

Agents with a shell (Claude Code, Cursor) can use git directly. git_access, or create git token in Settings, Site, returns a token and the clone command:

sh
git clone https://bot-<id>:<token>@git.galerne.cloud/sites/<project>.git
cd <project>
git switch -c agent/new-hero
# … change files …
git commit -am "Add a hero block"
git push origin agent/new-hero

Pushing a branch builds its preview and opens its content branch. Pushes to main are refused. Each call to git_access replaces your previous token; revoke removes it. A git token lasts 30 days: Galerne revokes it then, and git_access gives a new one. Operators revoke tokens sooner with pnpm -C apps/api git-tokens:expire --days <n> (--days 0 revokes all, --project <slug> limits it to one project). Agents limited to some branches use write_files, since git cannot hold them to those branches.

Git access is for people and agents; project API tokens use write_files. Leaving the project, or an agent switched off, deletes the git token. On macOS, a saved keychain login for the host can override the token in the URL: clone with git -c credential.helper= clone ….

Run the site on your machine#

site_env returns a .env.local with the API URL, the project, the preview secret and a new read token made for it. Point the studio at the local site with update_site_settings (previewUrl: "http://localhost:3000") to use the preview pane and the design tab against it. The same tool sets the routes per type, the public URL and the llms.txt switch.

Design tokens#

The template keeps its design tokens in theme/tokens.json (colors, typography, spacing, radii) and describes their shape in theme/tokens.schema.json. The site turns them into CSS custom properties when it builds.

update_theme changes some tokens on a branch, in one commit. Give only what changes, nested like the file:

json
{ "branch": "design/darker-accent", "tokens": { "colors": { "accent": "#0b5f59" }, "radii": { "large": "16px" } } }

null removes a token. Before the commit, the result is checked against the schema, and values that could break the CSS (such as ;, braces or <) are refused. The branch preview rebuilds, and the change goes through review like any other.

Mirrors#

In Settings, Site, Mirrors, give an empty repository on GitHub (https://github.com/<owner>/<repo>.git) or GitLab, and a token that may push to it. Forgejo then pushes every branch there on each change and every 8 hours. Forgejo keeps the token; Galerne does not store it.

The studio opens previews through the site's /api/galerne/preview route with the preview secret, the branch and the page to show. Settings, General shows the secret and rotates it. A hosted site gets the new secret and rebuilds right away; a site hosted elsewhere needs the new value in its environment.

Branch builds run code that anyone who writes on a branch can change, so a branch build could print its environment. They get their own credentials:

  • GALERNE_PREVIEW_SECRET in branch builds is a separate secret. Production does not accept it, so it only turns on draft mode in branch builds. The studio and preview_url use it for links to a branch build.
  • GALERNE_PREVIEW_TOKEN in branch builds has the read:drafts scope. It runs query, with drafts and on any branch, and no other tool or route, so export, comments, history and the site tools stay out of reach.
  • The webhook secret stays in production only.

What a branch writer can still do with these: read the drafts of every branch through query, as long as the token lives. Writers usually have that right already; the token stays valid after they leave the project. Rotating the preview secret in settings also rotates the branch secret; delete_site revokes the token. Sites created before branch builds had their own credentials get them at the next refresh_site; rotate the preview secret once then, since branch builds saw the production one.