# Sites and code

> Let Galerne host your website. One action creates a git repo from a site template and a site on Tramontane, then agents change the code on branches through MCP and people review code and content together.

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](https://tramontane.cloud), 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](/docs/nextjs.md)).

## 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](/docs/site-template.md), 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

| Tool | Right | What it does |
|---|---|---|
| `create_site` | admin | Creates the repo, the hosted site, its environment and the webhook |
| `refresh_site` | admin | Stores the site URL, wires the webhook, gives the site the current preview secrets again; `rebuild` builds production again |
| `list_files` | read | Files of a branch, under a folder if given |
| `read_file` | read | One file: text as UTF-8, others as base64, up to 1 MB |
| `write_files` | write on the branch | Creates, updates or deletes up to 200 files in one commit |
| `code_branches` | read | Branches with their last commit, content branch and preview |
| `code_changes` | read | Commits and files a branch changes compared to `main` |
| `build_status` | read | Latest builds, for one branch or all |
| `build_logs` | read | Log lines of a build, page by page |
| `preview_url` | read | Where to see a branch, and the link that opens it in draft mode |
| `delete_site` | admin, people only | Deletes the hosted site, the repo, git access, the site's tokens and webhook; content stays |
| `update_site_settings` | admin | Public URL, routes per type, preview URL, `llms.txt` |
| `site_env` | admin | A `.env.local` for running the site locally, with a new read token |
| `request_code_review` | request review | Asks for a review of the branch's code and content |
| `promote_code` | promote | Merges a code branch into `main`; `dryRun` only checks it |
| `update_theme` | write on the branch | Changes design tokens in `theme/tokens.json` in one commit |
| `set_mirror`, `list_mirrors` | admin, read | Mirrors the repo to your GitHub or GitLab |
| `git_access` | write | A token for plain git, valid 30 days |

The [tool reference](/docs/tools.md) 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.

## Preview links

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.
