--- url: /en/docs/backends/gitlab.md description: >- Configure GitLab backend in Sveltia CMS for managing content in GitLab repositories. --- # 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 editors to manage content seamlessly. ## Requirements * GitLab 16.3 or later. * A GitLab account. * A GitLab repository to store the content. * The Developer role or higher on the project, like Netlify/Decap CMS requires. The role can come from project membership, a parent group, or a group invited to the project or to a parent group. Users with the Guest or Reporter role can’t sign in. * Sveltia CMS installed in your project. If the configured branch is [protected](https://docs.gitlab.com/user/project/repository/branches/protected/) and doesn’t allow a user to push, e.g. when only Maintainers can push to it, collections using the [Simple Workflow](/en/docs/workflows/simple) and the [Asset Library](/en/docs/ui/asset-library) are read-only for that user, as they commit to the branch directly. Collections using the [Editorial Workflow](/en/docs/workflows/editorial) still work, as they commit to branches of their own, but the Publish button is only shown to users who can merge the entry’s merge request. ### CSP If your site uses a Content Security Policy (CSP), you may need to update it to allow requests to GitLab. See the [CSP documentation](/en/docs/security#setting-up-content-security-policy) 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. ::: code-group ```yaml [YAML] backend: name: gitlab repo: user/repo ``` ```toml [TOML] [backend] name = "gitlab" repo = "user/repo" ``` ```json [JSON] { "backend": { "name": "gitlab", "repo": "user/repo" } } ``` ```js [JavaScript] { 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. ::: code-group ```yaml [YAML]{4-5} backend: name: gitlab repo: owner/repo base_url: https://gitlab.example.com api_root: https://gitlab.example.com/api/v4 ``` ```toml [TOML]{4-5} [backend] name = "gitlab" repo = "owner/repo" base_url = "https://gitlab.example.com" api_root = "https://gitlab.example.com/api/v4" ``` ```json [JSON]{5-6} { "backend": { "name": "gitlab", "repo": "owner/repo", "base_url": "https://gitlab.example.com", "api_root": "https://gitlab.example.com/api/v4" } } ``` ```js [JavaScript]{5-6} { 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. Sveltia CMS uses the GitLab GraphQL API where possible. Its endpoint is inferred from the `api_root` option by replacing the `/api/v4` part with `/api/graphql`, e.g. `https://gitlab.example.com/api/graphql`. If your instance’s GraphQL endpoint is at a different URL, set it with the `graphql_api_root` option. The `base_url` option points to your GitLab server only when you use [PKCE authorization](#pkce-authorization). In that case, the OAuth authorization URL is made of `base_url` and the `auth_endpoint` option, which defaults to `oauth/authorize`. The `base_url` is not inferred from `api_root`, so it must be set for a self-hosted instance; otherwise, it defaults to `https://gitlab.com`. If your instance is served under a subpath, include the subpath in `base_url` rather than `auth_endpoint`. With the [authorization code flow](#authorization-code-flow), `base_url` is the URL of your OAuth client instead, which must be configured to use your GitLab server. See [OAuth Endpoint](/en/docs/backends#oauth-endpoint) for details. ## 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](/en/docs/workflows/local), you don’t need to set up authentication. ::: ::: warning 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](https://gitlab.com/gitlab-org/gitlab/-/issues/344609) in May 2022. Use the PKCE authorization instead. ::: ### Access Token (Quick Start) {#access-token} If you or a small team of developers are the only users of your CMS instance, you can use a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) (PAT) for authentication. This method is straightforward and doesn’t require setting up an OAuth app or updating the CMS configuration. Just click the “Sign In with Token” button on the login screen. The prompt dialog will provide a link to the token generation page on GitLab with the required scopes pre-selected. Generate a new token and copy it to the clipboard, then paste it into the prompt dialog to log in. The token will be stored in the browser’s local storage and used for subsequent API requests. You can [disable token authentication](/en/docs/backends#authentication-methods) if needed. ### PKCE Authorization (Recommended) {#pkce-authorization} 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: 1. Follow the instructions in the [GitLab documentation](https://docs.gitlab.com/integration/oauth_provider/) to create a new OAuth application. 2. Set the **Redirect URI** to your CMS admin URL, e.g., `https://your-domain.com/admin/`. 3. Uncheck the **Confidential** option. 4. Select the `api` scope. 5. 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: ::: code-group ```yaml [YAML]{4-5} backend: name: gitlab repo: owner/repo auth_type: pkce app_id: YOUR_CLIENT_ID ``` ```toml [TOML]{4-5} [backend] name = "gitlab" repo = "owner/repo" auth_type = "pkce" app_id = "YOUR_CLIENT_ID" ``` ```json [JSON]{5-6} { "backend": { "name": "gitlab", "repo": "owner/repo", "auth_type": "pkce", "app_id": "YOUR_CLIENT_ID" } } ``` ```js [JavaScript]{5-6} { 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) {#authorization-code-flow} 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. There are multiple options for the OAuth client, including our own Sveltia CMS Authenticator, third-party OAuth clients made for Netlify/Decap CMS, or using Netlify as an OAuth provider. #### Using Sveltia CMS Authenticator We provide our own OAuth client called [Sveltia CMS Authenticator](https://github.com/sveltia/sveltia-cms-auth) 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: ::: code-group ```yaml [YAML]{4} backend: name: gitlab repo: owner/repo base_url: YOUR_CLIENT_URL ``` ```toml [TOML]{4} [backend] name = "gitlab" repo = "owner/repo" base_url = "YOUR_CLIENT_URL" ``` ```json [JSON]{5} { "backend": { "name": "gitlab", "repo": "owner/repo", "base_url": "YOUR_CLIENT_URL" } } ``` ```js [JavaScript]{5} { backend: { name: "gitlab", repo: "owner/repo", base_url: "YOUR_CLIENT_URL", }, } ``` ::: #### Using Third-Party OAuth Client You can also use [third-party OAuth clients](https://decapcms.org/docs/external-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. The authorization URL is `base_url` followed by `/auth` by default, which is what clients made for Netlify/Decap CMS expect. If the client uses a different path, set the [`auth_endpoint`](/en/docs/backends#oauth-endpoint) option. If the client checks the site domain, you may need to set the [`site_domain`](/en/docs/backends#site-domain) option as well. ::: info 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. ::: #### 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. If your site is hosted on Netlify, you don’t need to install Sveltia CMS Authenticator or any other OAuth client. Instead, register a new OAuth app on GitLab and link it to your Netlify site. Here’s how: 1. Follow the instructions in the [GitLab documentation](https://docs.gitlab.com/integration/oauth_provider/) to create a new OAuth application. 2. Set the **Redirect URI** to `https://api.netlify.com/auth/done`. 3. Select the `api` scope. 4. Open the Netlify dashboard for your site and go to **Project configuration** > **Security** > **OAuth**. Note that this is not the **Identity** section, which is only used for Git Gateway and Netlify Identity. 5. Under **Authentication Providers**, click **Install Provider**, select **GitLab**, and [provide the Client ID and Client Secret](https://docs.netlify.com/manage/security/secure-access-to-sites/oauth-provider-tokens/#netlify-ui-settings) of your registered OAuth app. No changes are needed in Sveltia CMS, as long as `auth_type` and `base_url` are not set in your configuration file. Netlify identifies the site by its domain. If the CMS is served from a domain other than the one of your Netlify site, set the [`site_domain`](/en/docs/backends#site-domain) option. ::: info Disclaimer We are not affiliated with Netlify and do not endorse or maintain this authentication method. We only provide it to ensure backward compatibility with Netlify 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](https://docs.gitlab.com/topics/git/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](https://docs.gitlab.com/user/project/repository/signed_commits/web_commits/) 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](https://status.gitlab.com/) 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](/en/docs/workflows) are supported with the GitLab backend: * [Local Development Workflow](/en/docs/workflows/local) * [Simple Workflow](/en/docs/workflows/simple) * [Editorial Workflow](/en/docs/workflows/editorial) * [Open Authoring](/en/docs/workflows/open) ## Deployment [GitLab CI/CD](https://docs.gitlab.com/ci/) is a great choice for deploying Sveltia CMS sites hosted on GitLab. [GitLab Pages](https://docs.gitlab.com/user/project/pages/) can be used to host static sites for free. There are also other deployment options, including [Cloudflare Pages](https://developers.cloudflare.com/pages/configuration/git-integration/gitlab-integration/), [Netlify](https://www.netlify.com/integrations/gitlab/), and [Vercel](https://vercel.com/docs/git/vercel-for-gitlab). 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.