# Scheduled publishing and releases

> Publish or unpublish a document at a set time, group changes into a release that goes live together at its publish time, and what happens when the time comes.

Galerne can make content go live, or come down, at a time you choose. A single document gets a schedule. A set of changes that must go live together, such as a product launch or a new season, goes on a release: a branch with a publish time. Scheduling and releases are part of Pro and up.

## Schedule one document

In the studio, open the document, then **schedule** in its menu, and pick the action and the time. Agents and scripts call `schedule`:

```bash
curl https://api.galerne.cloud/p/acme/v1/docs/spring-sale/schedule \
  -H "Authorization: Bearer gal_…" -H "content-type: application/json" \
  -d '{"branch":"main","action":"publish","at":"2027-03-20T08:00:00+01:00"}'
```

| Input | What it does |
|---|---|
| `branch` | The branch of the document, usually `main` |
| `action` | `publish` or `unpublish` |
| `at` | ISO 8601 time with an offset, such as `2027-03-20T08:00:00+01:00` |

The answer is the schedule with its id and `runAt`. A document has at most one pending schedule per action and branch: scheduling the same action again replaces the time. Plan a publish and a later unpublish to show a page for a limited time. The editor lists the pending schedules of the document under its fields, each with a cancel button.

At that time, Galerne publishes or unpublishes the current draft, as the `Schedule` author in history, and sends the usual `doc.published` or `doc.unpublished` event, so sites refresh through their [webhooks](/docs/webhooks.md).

## List and cancel

`list_schedules` returns the pending schedules, soonest first, optionally for one `branch` or document `id`. `cancel_schedule` cancels one by its id and needs the same right as publishing on its branch:

```bash
curl https://api.galerne.cloud/p/acme/v1/schedules?id=harbours \
  -H "Authorization: Bearer gal_…"

curl -X DELETE https://api.galerne.cloud/p/acme/v1/schedules/sch_… \
  -H "Authorization: Bearer gal_…"
```

A release has its own way: set its `publishAt` to `null` with `update_branch`.

## Releases

A release is a branch with a publish time. Everything on it goes live together:

```bash
curl https://api.galerne.cloud/p/acme/v1/branches \
  -H "Authorization: Bearer gal_…" -H "content-type: application/json" \
  -d '{"name":"release/spring","title":"Spring collection","release":true,"publishAt":"2027-03-20T08:00:00+01:00"}'
```

Or from the CLI:

```bash
galerne branch create release/spring --release --publish-at 2027-03-20T08:00:00+01:00
```

People and agents then write on `release/spring` as on any branch, and preview it with its branch. Change the time, or remove it with `null`, with `update_branch`:

```bash
curl https://api.galerne.cloud/p/acme/v1/tools/update_branch \
  -H "Authorization: Bearer gal_…" -H "content-type: application/json" \
  -d '{"branch":"release/spring","publishAt":"2027-03-21T08:00:00+01:00"}'
```

The publish time must be at least a minute ahead. Setting it needs the rights to promote and to publish on `main`, since the release will do both.

At that time, Galerne promotes the release with `publish: true` and the branch side winning conflicting fields, then sends `release.published` with the list of promoted documents. Each merged document is published, and sites that revalidate on that event purge what it changed. You can also promote the release by hand earlier, from its review page. If something goes wrong, [roll back](/docs/branches.md#roll-back) the promotion: every document returns to its state before it.

## When a schedule cannot run

When a schedule runs, Galerne checks the rights that the person who set it has at that moment. If they left the project, or lost the right to publish or promote, the schedule does not run and keeps the reason. A schedule that fails (a document with validation errors, or a deleted one) keeps the error too.

Schedules are checked every 15 seconds, so content goes live within a few seconds of its time.
