Build a hosted site from start to finish
This tutorial builds the website of Atelier Rhône, a small design studio in Lyon. At the end it has pages made of blocks, a blog, a team page, English and French, a list of the studio's open source work synced from GitHub, its upcoming talks synced from its public agenda, and a release that goes live on its own. Galerne hosts the code and Tramontane serves it, both in the EU.
Every step can be done in two ways. By hand uses the studio, the CLI and your editor. With an agent gives a prompt to any agent that speaks MCP, which does the work through the project's MCP server. Both use the same tools, so they end in the same state, and you can change your mind at any step: do one by hand, give the next to the agent, then check its work in the studio.
You need:
- a Galerne account and a project on the Pro plan (review, releases and scheduling are part of Pro);
- Node.js 24 or later and pnpm, for the steps by hand;
- an MCP client, for the steps with an agent. Any client works for the content steps; the steps that change code need an agent that works in a terminal;
- a GitHub organisation or user with a few public repositories.
The project slug in this tutorial is atelier-rhone. If yours is different, use it everywhere you see that slug.
1. Create the project#
Only a person can create a project, so this part is the same in both modes:
- Sign in at
https://studio.galerne.cloud. - On the home page, in the New project card, type the name Atelier Rhône. The studio fills the slug
atelier-rhone. - Choose create project. The studio opens the new project, and its URL ends with
/p/atelier-rhone. - A new project is on the Free plan. In Settings, usage and plan, choose Pro.
Then give yourself or your agent access to it.
by hand
In Settings, API tokens, create a token with the admin scope and copy it: tokens start with gal_ and are shown once. Then install the CLI and log in:
npm i -g @galerne/cli
galerne login --project atelier-rhone --api https://api.galerne.cloudgalerne login asks for the token and keeps it in ~/.config/galerne/config.json.
with an agent
In Settings, agents and MCP, fill in New agent. Name it after your agent, give it the admin role so it may create the site and deploy schemas, and set its allowed branches to agent/*, and choose create agent. Leave may write on main and may promote branches off: the agent then works on branches and asks you for review, and you decide what goes live.
Connect your MCP client to https://api.galerne.cloud/p/atelier-rhone/mcp. Clients that support OAuth open a Galerne sign-in page, where you pick the agent. Others take a token: create one on the agent's page and send it as Authorization: Bearer gal_…. The server tells the agent to read the schema and the guidelines first, to work on a branch and to finish with a review request. Agents and permissions has the steps for each client.
2. Create the hosted site#
The project is empty, so the site starts from the starter template: pages made of 16 blocks, a blog, people, settings and UI strings in English and French. Galerne creates a private git repo from the template on its Forgejo server, a site on Tramontane in your Tramontane team, the site's tokens and secrets, and the webhook that refreshes pages on publish. Then it starts the first build.
by hand
In Settings, site, give the site a name and choose create site. The Builds card lists the first build, and show logs shows it as it runs. It takes a few minutes. When its status is ready, reload the page: Galerne stores the address Tramontane gave the site, wires the webhook, and shows open site. refresh does the same by hand. If the build failed, read its logs, then choose rebuild.
with an agent
Create the site for this project with the starter template. Follow the first build until it is ready, then refresh the site and give me its address.The agent calls create_site, follows the build with build_status and build_logs, then calls refresh_site. Running create_site again is safe: steps already done are kept.
Open the address: the site is online and empty, since the project has no content model yet.
3. Deploy the content model and the first content#
The template's content model is in galerne.config.ts, in the site repo. It goes to the project once, then content can follow.
by hand
First get a copy of the site code. The repo is private on Galerne's git server, git.galerne.cloud, so you clone it with a token:
- In Settings, site, find the Git access card and choose create git token.
- The studio shows a
git clonecommand once. Copy it and run it in a terminal.
The command looks like this:
git clone https://bot-4k2j9x0q1m3n:<token>@git.galerne.cloud/sites/atelier-rhone.gitbot-4k2j9x0q1m3nis the git user of your project. Galerne makes one per project, namedbot-followed by the project id, and gives it write access to this repo only.<token>is a git token for that user. It is shown once, works for 30 days, and each create git token replaces your previous one. Git keeps it in the remote URL of your clone, so keep the folder private.sites/atelier-rhoneis the repo: Galerne names it after the project slug.
You can push branches with this token. Pushes to main are refused: main only changes when you promote a branch in the studio.
Then deploy the model and load the template's sample content, which already describes a design studio in Lyon. npx galerne schema deploy uses the token you saved with galerne login in step 1, and the seed takes the same admin token:
cd atelier-rhone
pnpm install
npx galerne schema deploy
GALERNE_PROJECT=atelier-rhone GALERNE_API_URL=https://api.galerne.cloud GALERNE_ADMIN_TOKEN=gal_… pnpm seedReload the studio: the sidebar now lists the types of the model, such as Pages, Posts, People and Settings. The seed writes pages that use every block, posts, three people, the settings and the UI strings, in both languages, and publishes them. Open the site: it shows the home page. Rename the studio in Settings (the singleton in the sidebar), replace the people with your own, and publish.
with an agent
Read AGENTS.md and galerne.config.ts in the site repo. On a branch named agent/setup, deploy that content model, then fill the site for Atelier Rhône, a design studio in Lyon, in English and French: the settings, the UI strings, a home page with a hero, our services as cards and a call to action, an about page, a visit page with our address, and two people. Run the checks, then ask me for review.The agent reads the repo with read_file, deploys the model on the branch with deploy_schema and branch, then writes the content with create_doc and patch_doc. It adds pictures from public URLs with upload_media, each with alt text. check lists what is missing, such as a translation, and request_review sends you the branch.
In the studio, open Branches, then agent/setup. The review shows the schema it deployed and every document it wrote, field by field. Comment where you want changes: the agent reads them with branch_changes and fixes them on the same branch. When it looks right, choose approve, then promote and publish. The model reaches main first, then the content, and the site shows it within seconds.
People and agents can edit the same document at the same time. Open a page in the studio while the agent writes it, and its changes appear in the fields as it makes them.
4. Give the site your look#
The whole look of the site comes from theme/tokens.json: colors, fonts, type sizes, spacing and radii. Each token becomes a CSS variable that every block uses.
by hand
Open Design in the studio. Pick the accent color, the fonts and the type scale; the preview shows each block with the new values. Saving commits the tokens on a branch (design/theme by default), whose preview rebuilds; ask for review from the branch page and promote it like content. The design browser at /_design on the site shows every block and its variants.
with an agent
On a branch named agent/look, give the site a warmer look: a terracotta accent that keeps body text at 4.5:1 contrast in both color schemes, and a serif for headings. Send me the preview link, then ask for review.The agent changes only the tokens it needs with update_theme, in one commit. Tramontane builds a preview of the branch, and preview_url gives its link. Review it and promote it in the studio.
5. Sync the studio's work from GitHub#
The studio wants a page that lists its open source work. A data source pulls the repositories from the GitHub API into docs of a repo type, every hour. The site needs two things first: the repo type, and a block that shows those docs. That is a code change and a schema change, so both go on one branch. Git and the content use the same branch name, and one review covers the two.
Add the type and the block#
The type, in galerne.config.ts:
repo: {
title: 'Repository',
preview: { title: 'name', subtitle: 'language' },
fields: {
name: { type: 'string', required: true },
slug: { type: 'slug', from: 'name', required: true },
description: { type: 'text', localized: true },
url: { type: 'url' },
homepage: { type: 'url' },
language: { type: 'string' },
stars: { type: 'number', integer: true },
topics: { type: 'list', of: 'string' },
updatedAt: { type: 'datetime' },
},
},The description is localized: the source fills the English one, and the studio writes the French one by hand or with an agent.
by hand
Follow the steps of AGENTS.md in the repo, on a new git branch:
- Copy
blocks/post-listtoblocks/repo-list. Inschema.ts, keepheadingandlimitand addlanguage, to show only the repositories of one language. - In the component, query the
repotype ordered by-starswithgalerne.query, the waygetPostsinlib/galerne.tsdoes, and show the name, the description, the language and the stars of each. - Add the block to
blocksand topage.fields.blocks.ofingalerne.config.ts, add therepotype above, and add the component toblocks/index.ts. - Write the examples file, so the block shows in the design browser.
git switch -c site/work
pnpm dev # http://localhost:3100
git add -A && git commit -m "Add the repo type and the repoList block"
git push origin site/work
npx galerne schema deploy --branch site/workThe push builds a preview of the branch and opens the content branch site/work, so the schema deploys on that branch after the push. In the studio, switch to that branch, create a page named Work with the slug work in both languages, add a repoList block and save. Then open the branch review: it shows the code changes, the schema diff and the new pages together.
with an agent
On a branch named agent/work, add a repo type for our GitHub repositories (name, slug, localized description, url, homepage, language, stars, topics, updatedAt) and a repoList block that lists repositories ordered by stars, with an optional language filter. Follow AGENTS.md. Deploy the schema on the branch, add a Work page in English and French that uses the block, check the build, then ask for a code review.The agent writes the files with write_files, deploys the schema on its branch with deploy_schema, creates the pages with create_doc, and follows the preview build with build_status. request_code_review asks for one review of the code and the content.
Promote the branch in the studio with promote and publish. Galerne checks that the code merges into main, deploys the branch's schema, publishes the pages, then merges the code, and Tramontane builds production. The Work page is live, and it lists nothing yet.
Connect the source#
GitHub answers 60 requests an hour without a token, shared by every caller from the same address. Create a fine-grained token on GitHub with read access to public repositories only, and give it to the source as a secret. Galerne keeps secrets encrypted and never shows them again.
This definition fills repo docs from the repositories of your-org, and keeps them up to date every hour:
{
"name": "github",
"definition": {
"title": "GitHub repositories",
"type": "repo",
"fetch": {
"url": "https://api.github.com/orgs/your-org/repos?per_page=100&type=public",
"headers": { "Authorization": "Bearer {{secret.TOKEN}}" },
"pagination": { "type": "link" }
},
"key": "id",
"id": "repo-{{name}}",
"fields": {
"name": "name",
"slug": "name",
"description.en": "description",
"url": "html_url",
"homepage": "homepage",
"language": "language",
"stars": "stargazers_count",
"topics": "topics",
"updatedAt": "pushed_at"
},
"schedule": { "every": 60 },
"target": "review"
},
"secrets": { "TOKEN": "github_pat_…" }
}For a user account, the URL is https://api.github.com/users/<name>/repos. With "target": "review", each run that changes something writes on a branch and asks for review, so nothing reaches the site before someone looks. Use "main" to publish each run at once.
by hand
In Settings, data sources, choose create source. Pick the repo type, paste the URL, set pagination to link, add the header and the secret, and map each field as above. test fetches the API and shows the first docs it would write next to the items it read, and writes nothing. Save, then choose run now.
with an agent
Create a data source named github that fills the repo type from the public repositories of the GitHub organisation your-org, every hour, in review mode. Test it first and show me the first three docs it would write. I will add the GitHub token myself.The agent drafts the mapping, tries it with test_source, and saves it with create_source. Add the token in Settings, data sources, then choose run now: the agent has no right to publish on main, so it cannot start a run there itself.
The run writes on a branch named source/github/<date>-<time> and asks for review. Promote it, and the Work page lists the repositories. Each run is in the source's log with its counts. Run it twice and the second run writes nothing, because nothing changed.
Write over what the source says#
The source owns the fields it maps. Edit one and your edit wins: the field turns overridden, and later runs leave it alone. reset to source gives it back.
by hand
Open a repo doc and rewrite its English description in the studio's voice. Then write the French one, which the source never fills. Publish.
with an agent
On a branch named agent/repo-copy, rewrite the English description of our five most starred repositories in a plain, friendly voice, and translate each one into French. Ask for review.The agent queries the repos with query, patches the descriptions with patch_doc, and asks for review. Later syncs keep its English text, because the fields became overrides.
6. Plan a release#
A release is a branch with a publish time. Everything on it goes live together at that time, such as the studio's autumn exhibition: a page, a post and a new hero on the home page.
by hand
In the studio, create a branch named release/autumn, mark it as a release and set its publish time. Switch to it, write the exhibition page and the post, change the home page's hero, and look at the result in the preview pane next to the editor. From the CLI:
galerne branch create release/autumn --release --publish-at 2026-11-05T09:00:00+01:00with an agent
Prepare a release named release/autumn that publishes on 5 November at 9:00 Paris time. On it, add an exhibition page "Formes d'automne" in French and English, a post that announces it, and a hero on the home page that links to it. Ask for review.The agent creates the release with create_branch, with release and publishAt, and writes on it. Setting the time needs the rights to promote and to publish on main, so if the agent may not, it leaves the time for you to set in the studio.
Approve the release. At its time, Galerne promotes and publishes it, sends release.published, and the site refreshes the pages it changed. To publish a single document later, use schedule in its menu, or the schedule tool. If something goes wrong after the release, roll back the promotion from the branch's page: every document returns to its state before it.
7. Get told when something happens#
Every change in the project is an event. A webhook sends events to a URL of yours. Webhooks are set in the studio only.
In Settings, webhooks, add one for source.failed and release.published that posts to a small function of yours, which tells your team. The site already has its own webhook from step 2, for the pages to refresh on publish. Webhooks covers the payload and how to check its signature.
Programs and agents that run for a long time can follow events live instead, on the event stream.
8. Show the talks from your public agenda#
The studio hosts a talk every month and publishes it on OpenAgenda, the French platform cultural venues and cities use for their events. Events posted there also reach city and tourism agendas. A second data source shows them on the studio's own site, with their pictures, in both languages, and takes them down when they are over or cancelled.
This source adds what the GitHub one did not have: values that already come in two languages, images imported into the media library, dates, and a filter that lives in the API.
Add the type and the block#
As in step 5, the type and its block go on one branch with their code. The type, in galerne.config.ts:
talk: {
title: 'Talk',
preview: { title: 'title', subtitle: 'startsAt', media: 'image' },
fields: {
title: { type: 'string', localized: true, required: true },
slug: { type: 'slug', from: 'title', required: true },
summary: { type: 'text', localized: true },
body: { type: 'richText', localized: true },
image: { type: 'image' },
startsAt: { type: 'datetime', required: true },
endsAt: { type: 'datetime' },
place: { type: 'string' },
city: { type: 'string' },
status: { type: 'number', integer: true, description: 'OpenAgenda status: 6 means cancelled' },
},
},by hand
On a new git branch, copy blocks/repo-list to blocks/talk-list. Query the talk type ordered by startsAt, and show the image, the date, the title, the place and the summary of each talk, with a cancelled label when status is 6. Add the type, the block and the component as in step 5, deploy the schema on the branch, push, and add a Talks page in both languages that uses the block. Then ask for review and promote.
with an agent
On a branch named agent/talks, add a talk type (localized title, slug, localized summary and body, image, startsAt, endsAt, place, city, status) and a talkList block that lists upcoming talks by date, with their image, and shows "cancelled" when status is 6. Follow AGENTS.md. Deploy the schema on the branch, add a Talks page in English and French that uses the block, check the build, then ask for a code review.The agent works as in step 5: write_files, deploy_schema with the branch, create_doc, build_status and request_code_review.
Connect the agenda#
In OpenAgenda, open the studio's agenda and note its id, the number in its settings and in its API links. In your account settings, under API, copy the public key. It starts with oa_pk_, reads only the published events of public agendas, and is safe to share, so it is the right key for a site.
{
"name": "talks",
"definition": {
"title": "Talks from OpenAgenda",
"type": "talk",
"fetch": {
"url": "https://api.openagenda.com/v2/agendas/<agenda-id>/events?state=2&relative[]=current&relative[]=upcoming&detailed=1&size=100",
"headers": { "key": "{{secret.KEY}}" },
"items": "events"
},
"key": "uid",
"id": "talk-{{uid}}",
"fields": {
"title.en": "title.en",
"title.fr": "title.fr",
"slug": "slug",
"summary.en": "description.en",
"summary.fr": "description.fr",
"body.en": "longDescription.en",
"body.fr": "longDescription.fr",
"image": { "template": "{{image.base}}{{image.filename}}", "alt": "title.fr" },
"startsAt": "firstTiming.begin",
"endsAt": "lastTiming.end",
"place": "location.name",
"city": "location.city",
"status": "status"
},
"schedule": { "every": 30 },
"target": "main"
},
"secrets": { "KEY": "oa_pk_…" }
}What each part does:
state=2reads published events only, andrelative[]=current&relative[]=upcomingleaves out past ones. When a talk is over, it drops out of the answer, and the next run unpublishes its doc and marks it removed. It is never deleted, so its page and its history stay in the studio.- Titles and descriptions come from OpenAgenda in both languages, so each language maps to its own path of a localized field. One request fills both.
- The image is the 700 pixel version. Galerne downloads it once into the media library, with the French title as alt text, and serves it resized like any other image. An event without an image leaves the field empty.
longDescriptionis Markdown, which becomes rich text."target": "main"publishes each run at once: the agenda is already public, so there is nothing to review. A cancelled talk keeps its doc withstatus6, and the block shows it as cancelled.
size=100 covers the upcoming talks of a studio in one request, so the source has no pagination.
by hand
In Settings, data sources, choose create source, pick the talk type, paste the URL, add the key header with the secret, set the items path to events, and map the fields as above. test shows the first talks it would write, with their images. Save, then choose run now.
with an agent
Create a data source named talks that fills the talk type from our OpenAgenda agenda <agenda-id>: published events, current and upcoming only, both languages, with the image, every 30 minutes, publishing on main. Test it and show me the first three talks it would write. I will add the public key myself.The agent drafts the mapping and checks it with test_source, which reads the agenda and writes nothing. It saves the source with create_source. Add the key, then choose run now.
Open the Talks page: the upcoming talks are there, with their pictures, in English and in French. Change a talk's time in OpenAgenda, and the site shows the new time after the next run. Rewrite its summary in the studio, and your text stays, as an override, while the dates keep following OpenAgenda.
9. Use your own domain#
The site now lives at the address Tramontane gave it. Connect a domain such as atelier-rhone.fr when you are ready:
- In Tramontane, open the site, add the domain, and create the DNS records it shows at your registrar. Tramontane issues the certificate once the records resolve.
- Make the domain the site's main address in Tramontane.
- In Galerne, Settings, site, choose refresh, then rebuild. Galerne reads the address again, and the site builds with it, so the sitemap, the feeds and the hreflang links use the new domain. An agent does the same with
refresh_siteandrebuild: true.
You can also turn on Agent-readable site in Settings, general, so that llms.txt and the Markdown copy of each document link to pages on your domain. See site settings.
What you built#
- A content model in code, deployed through review: schema.
- Pages, posts and people in two languages: languages and translations, media.
- A hosted site whose code changes on branches with its content: sites and code, site template.
- A look made of tokens: design browser.
- External data from GitHub and OpenAgenda that stays in sync and that editors can still change: data sources.
- Changes that wait for review, and a release that goes live on its own: branches and review, scheduling and releases.
- Events for everything else: webhooks, event stream.
- An agent that does any of it, inside the limits you gave it: agents and permissions.
The code is yours: clone it with a git token, or mirror it to GitHub or GitLab in Settings, site, Mirrors.