docs menu

Branches and review

A branch is a set of content changes that waits until someone promotes it into main. main is the live content that sites read. People use branches for a redesign or a campaign; agents use them for every task.

Create a branch#

From the studio, with galerne branch create <name>, or with the create_branch tool:

json
{ "name": "agent/translate-de", "title": "German version", "description": "All pages, using the glossary" }

Names are lowercase and may use letters, digits, ., _, - and /, up to 100 characters. The Free plan includes 2 active branches and Pro 20; Business has no limit. Promote or close a branch to free its slot.

Fork on write#

A new branch is empty. Reading a document on the branch returns the version on main until the branch changes it. The first write on the branch copies the document into the branch and records the version it started from, the fork point. From then on the branch has its own copy, with its own drafts, published version and history.

So a branch always shows the whole site: its own changes, and main for everything else. A preview that queries with branch shows exactly what the site will look like after promotion.

In the studio, several people and agents can edit the same document on the same branch at once. Edits merge live, character by character.

Review#

When the work is done, ask for review with request_review, from the studio, or with galerne branch review --note "…". The branch status moves from open to in_review, and the review view shows:

  • every document created, edited or deleted on the branch, with a diff per field;
  • the schema deployed on the branch, if any, as a diff against main's;
  • fields that also changed on main since the fork, as conflicts;
  • validation errors and content checks of the changed documents;
  • comments on the branch, on documents and on single fields;
  • the review history: requests, approvals, changes requested, promotions.

Reviewers approve or ask for changes with a note. Only people can approve: an agent that calls approve gets a 403. Review, releases and scheduling are part of Pro and up.

branch_changes returns the same information as JSON, so an agent can read the reviewers' comments and fix what they asked.

Comments can mention people with @email or @[Name], and a comment with an assignee becomes a task with an optional due date. See comments and history.

Promote#

Promotion merges the branch into main:

json
{ "branch": "agent/translate-de", "publish": true }

Each changed document is merged against its fork point:

  • Text fields merge by character. If an editor fixed a typo on main while an agent rewrote the second paragraph on the branch, both changes survive.
  • Other fields merge three ways. A field changed only on the branch takes the branch value; a field changed only on main keeps the main value.
  • Blocks merge by _key. Blocks added, edited or moved on either side are kept, in order.
  • A field changed on both sides to different values is a conflict. So is a block one side deleted while the other edited it.

Without onConflict, promotion stops with a 409 conflict and lists each document and the conflicting paths. Settle them on the branch, or promote again with onConflict: "branch" or onConflict: "main" to pick the side that wins. The character-level merge of text fields still applies.

With publish: true, the merged documents are published at once and every one must pass validation; otherwise the promotion stops with a 422 and the field errors. Without it, the merged changes land as drafts on main and keep their published version until someone publishes. Pass docs to promote only some documents.

A branch can carry a schema change for the site code it holds (see changing the schema on a branch). Promotion deploys it on main first, in the same transaction, so the content lands on the model it was written for; a branch with only a schema change can be promoted too. When the site code lives in the same branch, the studio then merges the code: schema, content, code.

Promoted documents leave the branch, which reads through to main again. When nothing is left, the branch becomes merged. Agents promote only when their member has the promote right; most should ask for review instead.

Keep a branch up to date#

update_from_main (or galerne branch update) brings changes made on main since the fork into the branch. Text merges by character as in promotion; on other conflicting fields the branch value wins, and the result lists them.

Close a branch#

close_branch closes a branch without promoting it. Its changes stay in history.

Releases and scheduling#

A release is a branch with a publish date. Create one with release: true and an optional publishAt time:

json
{ "name": "release/spring", "title": "Spring collection", "release": true, "publishAt": "2027-03-20T08:00:00+01:00" }

At that time, Galerne promotes the release with publish: true and the branch side winning conflicts, and sends a release.published event. You can also promote it by hand at any time.

To publish or unpublish a single document at a time, use schedule (or the studio) with action and at. See scheduled publishing and releases.

Roll back#

Every promotion is recorded with the state of each document on main before it. From the studio you can roll a promotion back: each document returns to its previous draft and published state, as a new change in history, and Galerne sends a release.rolled_back event.

To undo a single document, restore_version restores a past version from get_history, whole or only some fields.

History#

Every change keeps who made it, person or agent, and when. get_history lists the versions of a document; pass two versions to get the field diff between them. The Free plan keeps 7 days of history, Pro 90 days and Business one year.