GitLab Backend

admin

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 two types of OAuth2 flows:

  • Web Application Flow, which works much like the GitHub OAuth flow described above.
  • Implicit Grant, which operates without the need for an authentication server.

Web Application Flow with Netlify

When using GitLab’s Web Application 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 Netlify 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 Netlify CMS config.yml file:
backend:
  name: gitlab
  repo: owner-name/repo-name # Path to your GitLab repository

Client-Side Implicit Grant (GitLab)

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 Netlify CMS instance as an OAuth application. For the Redirect URI, enter the address where you access Netlify 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 Netlify 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

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

Test Backend

admin

Test

You can use the test-repo backend to try out Netlify CMS without connecting to a Git repo. With this backend, you can write and publish content normally, but any changes will disappear when you reload the page. This backend powers the Netlify CMS demo site.

Note: The test-repo backend can’t access your local file system, nor does it connect to a Git repo, thus you won’t see any existing files while using it.

To enable this backend, add the following lines to your Netlify CMS config.yml file:

backend:
  name: test-repo

Git Gateway

admin

Git Gateway is a Netlify open source project that allows you to add editors to your site CMS without giving them direct write access to your GitHub or GitLab repository. (For Bitbucket repositories, use the Bitbucket backend instead.)

Git Gateway with Netlify

The Netlify Identity service can handle the authentication and provides a simple interface for user management. The Netlify CMS featured templates are working examples of this backend.

To use it in your own project stored on GitHub or GitLab, follow these steps:

  1. Head over to the Netlify Identity docs and follow the steps to get started.
  2. Add the following lines to your Netlify CMS config.yml file:
backend:
  name: git-gateway

Reconnect after Changing Repository Permissions

If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions. Find further instructions in the Netlify Git Gateway docs.

Git Gateway without Netlify

You can use Git Gateway without Netlify by setting up your own Git Gateway server and connecting it with your own instance of GoTrue (the open source microservice that powers Netlify Identity), or with any other identity service that can issue JSON Web Tokens (JWT).

To configure in Netlify CMS, use the same backend settings in your Netlify CMS config.yml file as described in Step 2 of the Git Gateway with Netlify Identity instructions above.

Netlify Large Media

admin

Netlify Large Media is a Git LFS implementation for repositories connected to Netlify sites. This means that you can use Git to work with large asset files like images, audio, and video, without bloating your repository. It does this by replacing the asset files in your repository with text pointer files, then uploading the assets to the Netlify Large Media storage service.

If you have a Netlify site with Large Media enabled, Netlify CMS (version 2.6.0 and above) will handle Large Media asset files seamlessly, in the same way as files stored directly in the repository.

Requirements

To use Netlify Large Media with Netlify CMS, you will need to do the following:

  • Upgrade Netlify CMS to version 2.6.0 or above.
  • Configure Netlify CMS to use the Git Gateway backend with Netlify Identity.
  • Configure the Netlify site and connected repository to use Large Media, following the Large Media docs on Netlify.

When these are complete, you can use Netlify CMS as normal, and the configured asset files will automatically be handled by Netlify Large Media.

Image transformations

All JPEG, PNG, and GIF files that are handled with Netlify Large Media also have access to Netlify’s on-demand image transformation service. This service allows you to request an image to match the dimensions you specify in a query parameter added to the image URL.

You can learn more about this feature in Netlify’s image transformation docs.

In repositories enabled with Netlify Large Media, Netlify CMS will use the image transformation query parameters to load thumbnail-sized images for the media gallery view. This makes images in the media gallery load significantly faster.

Note: When using this option all tracked file types have to be imported into Large Media. For example if you track *.jpg but still have jpg-files that are not imported into Large Media the backend will throw an error. Check the netlify docs on how to add previously committed files to Large Media.

You can disable the automatic image transformations with the use_large_media_transforms_in_media_library configuration setting, nested under backend in the CMS config.yml file:

backend:
  name: git-gateway
  ## Set to false to prevent transforming images in media gallery view
  use_large_media_transforms_in_media_library: false

Cloudinary

admin

Cloudinary is a digital asset management platform with a broad feature set, including support for responsive image generation and url based image transformation. They also provide a powerful media library UI for managing assets, and tools for organizing your assets into a hierarchy.

The Cloudinary media library integration for Netlify CMS uses Cloudinary’s own media library interface within Netlify CMS. To get started, you’ll need a Cloudinary account and Netlify CMS 2.3.0 or greater.

Creating a Cloudinary Account

You can sign up for Cloudinary for free. Once you’re logged in, you’ll need to retrieve your Cloud name and API key from the upper left corner of the Cloudinary console.

Cloudinary console screenshot

Connecting Cloudinary to Netlify CMS

To use the Cloudinary media library within Netlify CMS, you’ll need to update your Netlify CMS configuration file with the information from your Cloudinary account:

media_library:
  name: cloudinary
  config:
    cloud_name: your_cloud_name
    api_key: your_api_key

Note: The user must be logged in to the Cloudinary account connected to the api_key used in your Netlify CMS configuration.

Note: The Netlify CMS media library extensions for Cloudinary are not included in netlify-cms-app. If you’re using netlify-cms-app, you’ll need to register the media libraries yourself.

Security Considerations

Although this setup exposes the cloud_name and api_key publicly via the /admin/config.yml endpoint, this information is not sensitive. Any integration of the Cloudinary media library requires this information to be exposed publicly. To use this library or use the restricted Cloudinary API endpoints, the user must have access to the Cloudinary account login details or the api_secret associated with the cloud_name and api_key.

Netlify CMS configuration options

The following options are specific to the Netlify CMS integration for Cloudinary:

  • output_filename_only: (default: false)
    By default, the value provided for a selected image is a complete URL for the asset on Cloudinary’s CDN. Setting output_filename_only to true will instead produce just the filename (e.g. image.jpg). This should be true if you will be directly embedding cloudinary transformation urls in page templates. Refer to Inserting Cloudinary URL in page templates.
  • use_transformations: (default: true)
    If true, uses derived url when available (the url will have image transformation segments included). Has no effect if output_filename_only is set to true.
  • use_secure_url: (default: true)
    Controls whether an http or https URL is provided. Has no effect if output_filename_only is set to true.

Cloudinary configuration options

The following options are used to configure the media library. All options are listed in Cloudinary’s media library documentation, but only options listed below are available or recommended for the Netlify CMS integration:

Authentication

  • cloud_name
  • api_key

Media library behavior

Image transformations

The Cloudinary integration allows images to be transformed in two ways: directly within Netlify CMS via Cloudinary’s Media Library, and separately from the CMS via Cloudinary’s dynamic URL’s by inserting cloudinary urls.

Transforming images via Media Library

If you transform and insert images from within the Cloudinary media library, the transformed image URL will be output by default. This gives the editor complete freedom to make changes to the image output. There are two ways to configure image transformation via media library – globally and per field. Global options will be overridden by field options.

Global configuration

Global configuration, which is meant to affect the Cloudinary widget at all times, can be provided as seen below, under the primary media_library property. Settings applied here will affect every instance of the Cloudinary widget.

# global
media_library:
  name: cloudinary
  output_filename_only: false
  config:
    default_transformations:
      - - fetch_format: auto
          width: 160
          quality: auto
          crop: scale

Field configuration

Configuration can also be provided for individual fields that use the media library. The structure is very similar to the global configuration, except the settings are added to an individual field. For example:

# field
fields: # The fields each document in this collection have
- label: 'Cover Image'
  name: 'image'
  widget: 'image'
  required: false
  tagname: ''
  media_library:
    config:
      default_transformations:
        - fetch_format: auto
          width: 300    
          quality: auto
          crop: fill
          effect: grayscale

Inserting Cloudinary URL in page templates

If you prefer to provide direction so that images are transformed in a specific way, or dynamically retrieve images based on viewport size, you can do so by providing your own base Cloudinary URL and only storing the asset filenames in your content:

  • Either globally or for specific fields, configure the Cloudinary extension to only output the asset filename
# global
media_library:
  name: cloudinary
  output_filename_only: true
# field
media_library:
  name: cloudinary
  output_filename_only: true
  • Provide a dynamic URL in the site template
{{! handlebars example }}
<img src="https://res.cloudinary.com/<cloud_name>/<resource_type>/<type>/<transformations>/{{image}}"/>

Your dynamic URL can be formed conditionally to provide any desired transformations – please see Cloudinary’s image transformation reference for available transformations.