Orbit MD

Publishing · Setting up your GitHub repository

Step by step

1. Create the testing branch

Create a branch for editors’ saved changes — preview is a good name — and set it in Orbit’s config:

branches:
  default: preview   # the preview branch saves go to
  live: main         # the branch your live site is built from

Don’t require pull requests on the preview branch: Orbit pushes editors’ saves to it directly (and keeps the publish requests there).

2. Give your editors write access

On GitHub: Settings ▸ Collaborators and teams (or Collaborators on a personal account) ▸ add each editor with the Write role. In an organisation, a team such as Content editors with Write access is easiest to manage.

3. Protect the live branch

On GitHub: Settings ▸ Rules ▸ Rulesets ▸ New ruleset ▸ New branch ruleset.

  • Name it, e.g. Protect live, and set Enforcement status to Active.
  • Target branches ▸ Add a target ▸ Include default branch (or your live branch by name).
  • Branch protections ▸ tick Require a pull request before merging. This stops anyone pushing straight to live — except the people you add next. Its options (required approvals and so on) only apply to pull requests on GitHub, so the defaults are fine.
  • Restrict deletions and Block force pushes are ticked already — leave them on. Orbit never deletes the live branch or rewrites its history.

4. Let your approvers through

Still in the ruleset, under Bypass list ▸ Add bypass, add whoever approves content, and leave it set to Always allow (not For pull requests only — Orbit pushes the approved changes directly):

  • In an organisation: create a team such as Content approvers, add the approvers to it, and add that team to the bypass list. (Or add the Maintain role, and give approvers that role.)
  • On a personal account: the repository’s owner (the admin role) is the approver. Add the Repository admin role to the bypass list.

Don’t add the Write role — that would let every editor bypass the rule.

Click Create. GitHub’s own guide: Creating rulesets for a repository.

Rulesets on private repositories need a paid GitHub plan (Pro, Team or Enterprise); on the free plan they work on public repositories.

5. Add Orbit MD to the repository

For Sign in with GitHub, Orbit MD 1.1 and later. Go to github.com/apps/orbit-md ▸ Install (or Configure), choose the account or organisation that owns the site, then Only select repositories and the site. Orbit MD asks for two permissions only: to read and write the repository’s files, and to read its basic details.

You do this once per account or organisation; everyone with access then just signs in, and Orbit sets their role from GitHub — viewer, editor or approver. In an organisation, members who aren’t owners can request it from that page.

A view-only role needs an organisation. On a personal account, every collaborator you add can write; GitHub’s Read role exists only for organisation repositories.

6. Build both branches

Have your host build the preview branch as a preview site and the live branch as the real one, and put both addresses in Orbit (Settings ▸ General) so the Page tab’s Preview button and Unpublished link to them. See Astro’s deploy guides for your host.