GitLab

For repositories stored on GitLab, the gitlab backend allows CMS users to log in directly with their GitLab account. Note that all users must have push access to your content repository for this to work.

Note: GitLab default branch is protected by default, thus typically requires maintainer permissions in order for users to have push access.

The GitLab API allows for three types of OAuth2 flows:

• Authorization Code Flow, which works much like the GitHub OAuth flow described above.
• Authorization Code with PKCE Flow, which operates without the need for an authentication server.
• (DEPRECATED Implicit Grant Flow, which operates without the need for an authentication server.

Authorization Code Flow with Netlify

When using GitLab's Authorization Code Flow for authentication, you can use Netlify to handle the server-side authentication requests.

To enable it:

1. Follow the GitLab docs to add your Decap CMS instance as an OAuth application. For the Redirect URI, enter https://api.netlify.com/auth/done, and check the box for api scope.
2. Follow the Netlify docs to add your new GitLab Application ID and Secret to your Netlify site dashboard.
3. In your repository, add the following lines to your Decap CMS config.yml file:

backend:
  name: gitlab
  repo: owner-name/repo-name # Path to your GitLab repository

Client-Side PKCE Authorization

With GitLab's PKCE authorization, users can authenticate with GitLab directly from the client. To do this:

1. Follow the GitLab docs to add your Decap CMS instance as an OAuth application and uncheck the Confidential checkbox. For the Redirect URI, enter the address where you access Decap CMS, for example, https://www.mysite.com/admin/. For scope, select api.

2. GitLab gives you an Application ID. Copy this ID and enter it in your Decap CMS config.yml file, along with the following settings:

   backend:
     name: gitlab
     repo: owner-name/repo-name # Path to your GitLab repository
     auth_type: pkce # Required for pkce
     app_id: your-app-id # Application ID from your GitLab settings

   You can also use PKCE Authorization with a self-hosted GitLab instance. This requires adding api_root, base_url, and auth_endpoint fields:

   backend:
     name: gitlab
     repo: owner-name/repo-name # Path to your GitLab repository
     auth_type: pkce # Required for pkce
     app_id: your-app-id # Application ID from your GitLab settings
     api_root: https://my-hosted-gitlab-instance.com/api/v4
     base_url: https://my-hosted-gitlab-instance.com
     auth_endpoint: oauth/authorize

Note: In all cases, GitLab also provides you with a client secret. You should never store this in your repo or reveal it in the client.

GraphQL API

Note: not compatible with git-gateway

GraphQL allows to retrieve data using less individual API requests compared to a REST API. The current implementation uses the GraphQL API in specific cases, where using the REST API can be slow and lead to exceeding GitLab's rate limits. As we receive feedback and extend the feature, we'll migrate more functionality to the GraphQL API.

You can enable the GraphQL API for the GitLab backend by setting backend.use_graphql to true in your CMS config:

backend:
  name: gitlab
  repo: owner/repo # replace this with your repo info
  use_graphql: true

  # optional, defaults to 'https://gitlab.com/api/graphql'. Can be used to configure a self hosted GitLab instance.
  graphql_api_root: https://my-self-hosted-gitlab.com/api/graphql

Learn more about the benefits of GraphQL in the GraphQL docs.

(DEPRECATED) Client-Side Implicit Grant

Note: This method is not recommended and will be deprecated both by GitLab and in the OAuth 2.1 specification in the future.

With GitLab's Implicit Grant, users can authenticate with GitLab directly from the client. To do this:

1. Follow the GitLab docs to add your Decap CMS instance as an OAuth application and uncheck the Confidential checkbox. For the Redirect URI, enter the address where you access Decap CMS, for example, https://www.mysite.com/admin/. For scope, select api.
2. GitLab gives you an Application ID. Copy this ID and enter it in your Decap CMS config.yml file, along with the following settings:

backend:
    name: gitlab
    repo: owner-name/repo-name # Path to your GitLab repository
    auth_type: implicit # Required for implicit grant
    app_id: your-app-id # Application ID from your GitLab settings

You can also use Implicit Grant with a self-hosted GitLab instance. This requires adding api_root, base_url, and auth_endpoint fields:

backend:
    name: gitlab
    repo: owner-name/repo-name # Path to your GitLab repository
    auth_type: implicit # Required for implicit grant
    app_id: your-app-id # Application ID from your GitLab settings
    api_root: https://my-hosted-gitlab-instance.com/api/v4
    base_url: https://my-hosted-gitlab-instance.com
    auth_endpoint: oauth/authorize