Connecting a site

Once you’ve created a site, switch your backend to turbo-github, or turbo-gitlab if the repo is on GitLab.

Install

The Turbo backends are part of Decap CMS from 3.17.0 onward, in the stable release.

<script src="https://cdn.jsdelivr.net/npm/decap-cms@^3.0.0/dist/decap-cms.js"></script>

The standard script tag above already loads them.

npm install decap-cms-app

With npm, installing decap-cms-app registers both Turbo backends, so there’s nothing extra to import.

If your site loads decap-cms@beta or a version pinned to a -beta build, switch it to the stable release.

Configuration

backend:
  name: turbo-github # or turbo-gitlab
  turbo_site_id: your-site-id
  branch: main # optional

turbo_site_id is the UUID on the site’s Overview tab, and the only value you have to set by hand. Everything else the backend needs — the Supabase project, the proxy endpoint, the repo — is fetched from the control plane at load time, keyed on that ID. Infrastructure changes on Turbo’s side never require a config.yml edit.

repo and branch

These behave differently from every other backend, and differently from each other:

• repo is ignored. The value on the site row wins. The proxy resolves permissions from it, so a stale local copy is exactly what produces requested repo does not match. Change the repo in the dashboard, not here.
• branch wins if you set it, and falls back to the site row if you don’t. That is deliberate: one Turbo site can back several deploys of the same repo, each editing its own branch — production on main, staging on develop — with the same turbo_site_id in both configs.

Logging in

The login screen shows Login with Turbo and opens a popup. You need access to that specific site — a Turbo account alone isn’t enough.

Sessions refresh in the background, so editors aren’t logged out mid-edit.

Admin URLs, deploy previews and branch deploys

Turbo only hands a login to a CMS served from one of the site’s admin interface URLs, set on the site’s Overview tab. Only the origin counts — protocol, host and port — so the path doesn’t have to match. Add one URL per line for every place the CMS runs: production, a staging domain, http://localhost:1313 for local development.

Deploy previews and branch deploys get a new hostname for every build, so list them with a wildcard:

https://example.com/admin/
https://*--your-site.netlify.app/admin/

The rules:

• One * per URL, in the leftmost part of the hostname only. https://*--your-site.netlify.app and https://*.example.com work; https://preview.*.example.com doesn’t.
• No bare wildcard on a shared hosting domain. https://*.netlify.app, https://*.vercel.app or https://*.pages.dev would match every customer of that host, so Turbo refuses them. Anchor the wildcard to your own site’s name, the way your host names its previews — for example *--your-site.netlify.app on Netlify.
• The * never spans a dot. *.example.com matches preview.example.com but not a.b.example.com.
• Put your main admin URL first. The organization dashboard links to the first URL in the list.

Each origin keeps its own login, so an editor opening a deploy preview logs in once there too. They still need access to the site; a matching URL doesn’t grant it.

Commit attribution

Different on each backend — check your own git log before assuming.

GitLab sends your Turbo display name and account email as author_name and author_email, so you are the commit author. The committer is the GitLab account that authorized the Git connection.

GitHub makes the App the author and credits you on a trailer:

Author: decap-turbo[bot] <...>

    Update post "my first post"

    Co-authored-by: Your Name <you@example.com>

GitHub’s createCommitOnBranch authors as whoever holds the token, with no override. The alternative is the multi-step REST sequence, which costs three extra round trips on every save. GitHub renders co-author avatars and counts the commit toward your contributions, so attribution is still visible — on the trailer rather than the author field. Point any tooling that reads git log --author at the trailer instead.

Config path

Turbo reads your collections from the file at the site’s config path to support per-collection permissions.

Media uploads

To keep uploads out of your repo, see Media library. Pro and above.