GitLab Backend

GitLab is a popular Git hosting service that offers a wide range of features for developers and teams. Sveltia CMS provides robust support for GitLab repositories, allowing you to manage your content seamlessly.

Requirements

GitLab 16.3 or later.
A GitLab account.
A GitLab repository to store your content.
Sveltia CMS installed in your project.

CSP Settings

If your site uses a Content Security Policy (CSP), You may need to update it to allow requests to GitLab. See the CSP documentation for more details.

Configuration

The base configuration for the GitLab backend is straightforward. You need to specify the name of the backend as gitlab and provide the repo option with the format owner/repo, where owner is your GitLab username or organization name, and repo is the repository name.

YAMLTOMLJSONJavaScript

yaml

backend:
  name: gitlab
  repo: user/repo

toml

[backend]
name = "gitlab"
repo = "user/repo"

json

{
  "backend": {
    "name": "gitlab",
    "repo": "user/repo"
  }
}

{
  backend: {
    name: "gitlab",
    repo: "user/repo",
  },
}

If you use subgroups, include them in the owner part, e.g., group/subgroup/repo.

Self-Hosted GitLab Instances

By default, Sveltia CMS uses the public GitLab instance at https://gitlab.com. If you use a self-hosted GitLab instance, you need to set the base_url and api_root options in your backend configuration to point to your GitLab server URL.

YAMLTOMLJSONJavaScript

yaml

backend:
  name: gitlab
  repo: owner/repo
  base_url: https://gitlab.example.com
  api_root: https://gitlab.example.com/api/v4

toml

[backend]
name = "gitlab"
repo = "owner/repo"
base_url = "https://gitlab.example.com"
api_root = "https://gitlab.example.com/api/v4"

json

{
  "backend": {
    "name": "gitlab",
    "repo": "owner/repo",
    "base_url": "https://gitlab.example.com",
    "api_root": "https://gitlab.example.com/api/v4"
  }
}

{
  backend: {
    name: "gitlab",
    repo: "owner/repo",
    base_url: "https://gitlab.example.com",
    api_root: "https://gitlab.example.com/api/v4",
  },
}

The API version for GitLab is v4, so make sure to include /api/v4 in the api_root option.

Authentication

There are multiple ways to authenticate with GitLab when using Sveltia CMS. You can choose the method that best fits your needs. Using an access token is the simplest way to get started, but PKCE authorization is recommended if your CMS instance is used by multiple users or non-technical users because it’s more user-friendly and secure.

TIP

If you plan to only work with your local repository, you don’t need to set up authentication.

Breaking change from Netlify/Decap CMS

The deprecated client-side implicit grant flow for the GitLab backend is not supported in Sveltia CMS. It was removed from GitLab 15.0 in May 2022. Use the PKCE authorization instead.

Access Token (Quick Start)

If you or a small team of developers are the only users of your CMS instance, you can use a personal access token (PAT) for authentication. This method is straightforward and doesn’t require setting up an OAuth app.

Just click the “Sign In with Token” button on the login screen and enter your token. The prompt dialog will provide a link to the token generation page on GitLab with the required scopes pre-selected.

PKCE Authorization (Recommended)

To use PKCE authorization with Sveltia CMS, you need to register a new OAuth app on GitLab and update your Sveltia CMS configuration file accordingly. Here’s how:

Follow the instructions in the GitLab documentation to create a new OAuth application.
Set the Redirect URI to your CMS admin URL, e.g., https://your-domain.com/admin/.
Uncheck the Confidential option.
Select the api scope.
Copy the Client ID of your registered OAuth app.

Then, update your Sveltia CMS configuration file to include the auth_type and app_id options:

YAMLTOMLJSONJavaScript

yaml

backend:
  name: gitlab
  repo: owner/repo
  auth_type: pkce
  app_id: YOUR_CLIENT_ID

toml

[backend]
name = "gitlab"
repo = "owner/repo"
auth_type = "pkce"
app_id = "YOUR_CLIENT_ID"

json

{
  "backend": {
    "name": "gitlab",
    "repo": "owner/repo",
    "auth_type": "pkce",
    "app_id": "YOUR_CLIENT_ID"
  }
}

{
  backend: {
    name: "gitlab",
    repo: "owner/repo",
    auth_type: "pkce",
    app_id: "YOUR_CLIENT_ID",
  },
}

Users’ OAuth tokens will be automatically renewed as needed, so there’s no need to worry about token expiration.

Authorization Code Flow (Legacy)

PKCE authorization is the recommended way to authenticate with GitLab. However, if you need to use the authorization code flow for some reason, you can follow the instructions below. This method requires a backend server to keep the client secret safe.

Using Netlify

For backward compatibility with Netlify CMS, Sveltia CMS supports the authorization code flow using Netlify as an OAuth client. It’s the default authentication method if you don’t configure authentication explicitly, and you don’t need to set up a backend server yourself.

To set it up, you need to register a new OAuth app on GitLab and update your Sveltia CMS configuration file accordingly. Here’s how:

Follow the instructions in the GitLab documentation to create a new OAuth application.
Set the Redirect URI to https://api.netlify.com/auth/done.
Select the api scope.
Open the Netlify site dashboard and provide the Client ID and Client Secret of your registered OAuth app.

No configuration changes are needed in Sveltia CMS.

Using Sveltia CMS Authenticator

We provide our own OAuth client called Sveltia CMS Authenticator that you can deploy on Cloudflare Workers. Follow the instructions in the repository to deploy the authenticator and update your CMS configuration file to include the base_url option pointing to your authenticator URL:

YAMLTOMLJSONJavaScript

yaml

backend:
  name: gitlab
  repo: owner/repo
  base_url: YOUR_CLIENT_URL

toml

[backend]
name = "gitlab"
repo = "owner/repo"
base_url = "YOUR_CLIENT_URL"

json

{
  "backend": {
    "name": "gitlab",
    "repo": "owner/repo",
    "base_url": "YOUR_CLIENT_URL"
  }
}

{
  backend: {
    name: "gitlab",
    repo: "owner/repo",
    base_url: "YOUR_CLIENT_URL",
  },
}

Using Third-Party OAuth Client

You can also use third-party OAuth clients made for Netlify/Decap CMS. These clients support various languages and hosting services, and they should work with Sveltia CMS as well without any modifications.

The setup process is similar to using Sveltia CMS Authenticator. You need to register a new OAuth app on GitLab and configure the third-party client with the app credentials. Then, update your CMS configuration to include the base_url option pointing to your OAuth client URL, like in the example above.

Disclaimer

Third-party clients are not reviewed or maintained by the Sveltia CMS team. Use them at your own risk. Some clients may not be compatible with Sveltia CMS.

Features

Git LFS

Git Large File Storage (LFS) is supported out of the box in the GitLab backend. Just make sure to enable LFS in your GitLab repository settings.

GraphQL

GraphQL support is enabled for GitLab repositories. Sveltia CMS uses the GitLab GraphQL API to interact with the repository, which provides better performance and flexibility compared to the REST API. No additional configuration is needed to enable GraphQL support.

Commit Signing

Signed commits are supported in self-hosted GitLab instances but disabled by default. See the GitLab documentation for more details on setting up commit signing.

Signed commits are not supported in the public GitLab instance at gitlab.com at this time.

Service Status Checking

Service status checking is available for GitLab repositories, unless you’re using a self-hosted GitLab instance. Sveltia CMS periodically checks the status of the GitLab service to ensure that it is operational. If any incidents are detected, a notification banner will be displayed in the CMS UI to inform users of potential issues that may affect their workflow.

Workflows

The following content management workflows are supported with the GitLab backend:

Deployment

GitLab CI/CD is a great choice for deploying Sveltia CMS sites hosted on GitLab. GitLab Pages can be used to host static sites for free.

There are also other deployment options, including Cloudflare Pages, Netlify, and Vercel. They provide seamless integration with GitLab repositories and support automatic deployments on push, with additional benefits like serverless functions, storage and AI integrations.

Choose the deployment platform that best fits your needs and follow their documentation to set up continuous deployment for your Sveltia CMS site.

Framework Guides

Migration Guides

Configuration Basics

Backends

Media Storage

Collections

Fields

JavaScript API

User Interface

Workflows

Integrations

GitLab Backend

Requirements

Configuration

Self-Hosted GitLab Instances

Authentication

Access Token (Quick Start)

PKCE Authorization (Recommended)

Authorization Code Flow (Legacy)

Using Netlify

Using Sveltia CMS Authenticator

Using Third-Party OAuth Client

Features

Git LFS

GraphQL

Commit Signing

Service Status Checking

Workflows

Deployment

GitLab Backend ​

Requirements ​

Configuration ​

Self-Hosted GitLab Instances ​

Authentication ​

Access Token (Quick Start) ​

PKCE Authorization (Recommended) ​

Authorization Code Flow (Legacy) ​

Using Netlify ​

Using Sveltia CMS Authenticator ​

Using Third-Party OAuth Client ​

Features ​

Git LFS ​

GraphQL ​

Commit Signing ​

Service Status Checking ​

Workflows ​

Deployment ​

GitLab Backend

Requirements

Configuration

Self-Hosted GitLab Instances

Authentication

Access Token (Quick Start)

PKCE Authorization (Recommended)

Authorization Code Flow (Legacy)

Using Netlify

Using Sveltia CMS Authenticator

Using Third-Party OAuth Client

Features

Git LFS

GraphQL

Commit Signing

Service Status Checking

Workflows

Deployment