# Connecting a site

Source: https://decapcms.org/docs/turbo-connecting-a-site/ (updated 2026-10-16)


Once you've [created a site](https://decapcms.org/docs/turbo-getting-started/#create-a-site), switch your backend to `turbo-github`, or `turbo-gitlab` if the repo is on GitLab.

<div style="position:relative;padding-top:56.25%;"><iframe src="https://player.mediadelivery.net/embed/756464/b3030891-23dc-4cf0-852c-7660eb538859?autoplay=false&loop=false&muted=false&preload=false&responsive=true" loading="lazy" style="border:0;position:absolute;top:0;height:100%;width:100%;" allow="accelerometer;gyroscope;autoplay;encrypted-media;picture-in-picture;fullscreen;" allowfullscreen="true"></iframe></div>

## Install

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

```html
<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.

```sh
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

```yaml
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](https://decapcms.org/docs/turbo-roles-and-members/) — 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](https://decapcms.org/docs/turbo-roles-and-members/); 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](https://decapcms.org/docs/turbo-getting-started/#connect-your-git-provider).

**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](https://decapcms.org/docs/turbo-roles-and-members/#site-roles).

| Generator | Typical path |
|---|---|
| Plain static site / Jekyll | `admin/config.yml` |
| Hugo | `static/admin/config.yml` |
| Next.js | `public/admin/config.yml` |

## Media uploads

To keep uploads out of your repo, see [Media library](https://decapcms.org/docs/turbo-media-proxy/). Pro and above.