Set the site up from opend.config.yaml

The site block of opend.config.yaml declares how the hosted site is set up: who may read it, which versions readers can pick, how releases group into lines and which branches publish. With it, installing the GitHub App is the only step a person takes.

Fields

Every field is optional and takes the same values as the admin API. A field the block sets belongs to the repository; a field it leaves out stays yours to manage in the admin console.

Field	Values	Same as
`releaseRefs`	branch and tag patterns, such as `[main, 'v']` or `['docs/']`	The release branches and tags on Docs source (`releaseRefs` of `POST /admin/api/repos`). Quote patterns that start with `*`. A branch it newly matches builds on its next push.
`releaseLines`	`major` or `minor`	Release lines by major or minor version
`access`	`private` or `public`	Make a site public or private
`publicEntitlements`	`{products, features, version}`, or `null`	What anonymous visitors of a public site see (Make a site public or private). The `version` may be `latest`. Products and features must be declared under `attributes`.
`versionPicker`	`{mode: off}`, `reader`, `fixed` with `version`, `list` with `versions`, or `live`	Let readers choose the version they read

opend validate checks the block like the rest of the file: an unknown field, a bad value or an undeclared product is an invalid-config error naming the field, such as site.access: Invalid option.

Example: a manual published per minor version

Docs in manual/, one docs/0.23-style branch per minor version, public with the free plan's content, and a version menu of every live line:

title: Product Manual
release: '0.23'
map: maps/manual.ditamap
attributes:
  product: [free, lite, business, enterprise, self-host]
site:
  releaseRefs: ['docs/*']
  releaseLines: minor
  access: public
  publicEntitlements: { products: [free], version: latest }
  versionPicker: { mode: live }

Which build's block applies

A build that goes live on the site's newest release line (the highest version, such as 0.23 next to 0.22) applies its block, in the same transaction that makes it live: no reader is ever served the new release under the old settings. Builds of older lines, such as a fix pushed to docs/0.22, and builds a newer push already replaced change nothing, so the settings never go back to an older branch's. Every change is in the audit log as repo:opend.config.yaml, with the branch and commit it came from, and every replica drops its cached pages at once.

Settings the block leaves out keep their values. Removing the block, or a field from it, hands the setting back to the console with its last value.

In the admin console

Settings the repository declares show Set by opend.config.yaml on Site & access and Docs source, with the branch and commit, and are read-only. The admin API answers 409 to a change to one of them, and a seed file leaves them as they are. To change one, change the repository.

A repository's settings are trusted like its content: anyone who can push to a release branch can make the site public. Protect those branches on GitHub (required reviews) if that matters.

Connecting the repository by itself

When the site has no docs source yet and the GitHub App can access exactly one repository, the site connects it without anyone choosing it:

the docs folder is where opend.config.yaml is on the default branch: the root, else the only one up to three folders down (hidden folders and node_modules aside), else the only one with a site block;
the release branches are its site.releaseRefs, or the default branch;
every release branch's head is queued to build, and the first build applies the rest of the block.

It happens when the installation completes (GitHub's return to the site, or the hosting provider's), on the next visit to the admin console's Overview or Docs source, on the first push from the repository, and on each poll of a site that polls. With several repositories, several candidate folders, or an invalid site block, nothing is connected: the Overview says why and Docs source offers the picker as before.