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:
- 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 forapi
scope. - Follow the Netlify docs to add your new GitLab Application ID and Secret to your Netlify site dashboard.
- 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:
-
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, selectapi
. -
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
, andauth_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:
- 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, selectapi
. - 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