Skip to content

Commit

Permalink
Add GitLab backend to docs (#1413)
Browse files Browse the repository at this point in the history
  • Loading branch information
@verythorough @erquhart
verythorough authored and erquhart committed Jun 12, 2018
1 parent 8202aa4 commit b47bb66
Show file tree
Hide file tree
Showing 7 changed files with 99 additions and 45 deletions.
14 changes: 8 additions & 6 deletions website/site/content/docs/add-to-your-site.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ menu:

# Add Netlify CMS to Your Site

Netlify CMS is adaptable to a wide variety of projects. The only inflexible requirement is that your site content must be written in markdown, JSON, YAML, or TOML files, stored in a repo on [GitHub](https://github.com/). (If you're partial to another Git hosting service, check out the PRs in progress for [GitLab](https://github.com/netlify/netlify-cms/pull/517) and [Bitbucket](https://github.com/netlify/netlify-cms/pull/525) support.)
Netlify CMS is adaptable to a wide variety of projects. The only inflexible requirement is that your site content must be written in markdown, JSON, YAML, or TOML files, stored in a repo on [GitHub](https://github.com/) or [GitLab](https://about.gitlab.com/). You can also create your own custom backend, or if you're interested in Bitbucket support, that's [coming soon](https://github.com/netlify/netlify-cms/pull/525).

This tutorial will guide you through the steps for adding Netlify CMS to a site that's built with a common [static site generator](https://www.staticgen.com/), like Jekyll, Hugo, Hexo, or Gatsby. Alternatively, you can [start from a template](https://www.netlifycms.org/docs/start-with-a-template) or dive right into to [configuration options](https://www.netlifycms.org/docs/configuration-options).

Expand Down Expand Up @@ -80,7 +80,7 @@ Configuration will be different for every site, so we'll break it down into part

### Backend

Because we're using GitHub and Netlify for our hosting and authentication, backend configuration is fairly strightforward. You can start your `config.yml` file with these lines:
We're using [Netlify](https://www.netlify.com) for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward. You can start your Netlify CMS `config.yml` file with these lines:

```yaml
backend:
Expand All @@ -92,7 +92,9 @@ These lines specify your backend protocol and your publication branch. Git Gatew

### Editorial Workflow

By default, saving a post in the CMS interface will push a commit directly to the publication branch specified in `backend`. However, you also have the option to enable the [Editorial Workflow](https://www.netlifycms.org/docs/configuration-options/#publish-mode), which adds an interface for drafting, reviewing, and approving posts. To do this, add the following line to your `config.yml`:
**Note:** Editorial workflow only works for the GitHub backend (and Git Gateway when used with GitHub). Support for other backends is [coming soon](https://github.com/netlify/netlify-cms/issues/568).

By default, saving a post in the CMS interface will push a commit directly to the publication branch specified in `backend`. However, you also have the option to enable the [Editorial Workflow](https://www.netlifycms.org/docs/configuration-options/#publish-mode), which adds an interface for drafting, reviewing, and approving posts. To do this, add the following line to your Netlify CMS `config.yml`:

```yaml
# This line should *not* be indented
Expand Down Expand Up @@ -198,7 +200,7 @@ Let's break that down:

As described above, the `widget` property specifies a built-in or custom UI widget for a given field. When a content editor enters a value into a widget, that value will be saved in the document front matter as the value for the `name` specified for that field. A full listing of available widgets can be found in the [Widgets doc](https://www.netlifycms.org/docs/widgets).

Based on this example, you can go through the post types in your site and add the appropriate settings to your `config.yml` file. Each post type should be listed as a separate node under the `collections` field.
Based on this example, you can go through the post types in your site and add the appropriate settings to your Netlify CMS `config.yml` file. Each post type should be listed as a separate node under the `collections` field.

### Filter

Expand Down Expand Up @@ -226,12 +228,12 @@ Netlify offers a built-in authentication service called Identity. In order to us

### Enable Identity and Git Gateway

Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have GitHub accounts or commit access on your repo. From your site dashboard on Netlify:
Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:

1. Go to **Settings > Identity**, and select **Enable Identity service**.
2. Under **Registration preferences**, select **Open** or **Invite only**. In most cases, you'll want only invited users to access your CMS, but if you're just experimenting, you can leave it open for convenience.
3. If you'd like to allow one-click login with services like Google and GitHub, check the boxes next to the services you'd like to use, under **External providers**.
4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This will authenticate with GitHub and generate a GitHub API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access the CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).
4. Scroll down to **Services > Git Gateway**, and click **Enable Git Gateway**. This will authenticate with your Git host and generate an API access token. In this case, we're leaving the **Roles** field blank, which means any logged in user may access the CMS. For information on changing this, check the [Netlify Identity documentation](https://www.netlify.com/docs/identity/).

### Add the Netlify Identity Widget

Expand Down
101 changes: 76 additions & 25 deletions website/site/content/docs/authentication-backends.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,19 @@ menu:
---
# Authentication & Backends

Netlify CMS stores content in your GitHub repository. (GitLab and Bitbucket coming soon!) In order for this to work, you need to authenticate with GitHub, and that requires a server. We have a few options for handling this.
Netlify CMS stores content in your GitHub or GitLab repository. (Bitbucket [coming soon](https://github.com/netlify/netlify-cms/pull/525)!) In order for this to work, you need to authenticate with your Git host, and in most cases that requires a server. We have a few options for handling this.

**Note:** some static site generators have plugins for optimized integration with Netlify CMS, and starter templates may utilize these plugins. If you're using a starter template, read the template documentation before proceeding, as their instructions may differ.

## Git Gateway with Netlify Identity

[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct push access to your GitHub repository. [Netlify Identity](https://www.netlify.com/docs/identity/) service handles the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](https://www.netlifycms.org/docs/start-with-a-template) are working examples of this backend.
[Git Gateway](https://github.com/netlify/git-gateway) is a Netlify open source project that allows you to add editors to your site CMS without giving them direct push access to your GitHub or GitLab repository. [Netlify Identity](https://www.netlify.com/docs/identity/) service can handle the authentication and provides a simple interface for user management. The Netlify CMS [featured templates](https://www.netlifycms.org/docs/start-with-a-template) are working examples of this backend.

To use it in your own project, follow these steps:

1. Head over to the [Netlify Identity docs](https://www.netlify.com/docs/identity) and follow the
steps to get started.
2. Add the following lines to your `config.yml` file:
2. Add the following lines to your Netlify CMS `config.yml` file:

```yaml
backend:
Expand All @@ -30,19 +30,18 @@ To use it in your own project, follow these steps:
```
3. Optionally, you can assign roles to users in your Netlify dashboard, and then limit which
roles can access the CMS by defining the `accept_roles` field in the `config.yml` example above.
roles can access the CMS by defining the `accept_roles` field as shown in the example above.
Otherwise `accept_roles` can be left out, and all Netlify Identity users on your site will have access.

## Git Gateway without Netlify

You can use [Git Gateway](https://github.com/netlify/git-gateway) without Netlify by setting up your own Git Gateway server and connecting it with your own instance of [GoTrue](https://www.gotrueapi.org) (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 `config.yml` file as described in Step 2 of the [Git Gateway with Netlify Identity](#git-gateway-with-netlify-identity) instructions above.
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](#git-gateway-with-netlify-identity) instructions above.

## GitHub Backend

The GitHub backend allows CMS users to log in directly with their GitHub account. Note that the
user's GitHub account must have push access to your content repository for this to work.
For repositories stored on GitHub, the `github` backend allows CMS users to log in directly with their GitHub account. Note that all users must have push access to your content repository for this to work.

Because Github [requires a
server](https://github.com/netlify/netlify-cms/issues/663#issuecomment-335023723) for
Expand All @@ -52,17 +51,79 @@ To enable it:

1. Follow the authentication provider setup steps in the [Netlify
docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your `config.yml` file:
2. Add the following lines to your Netlify CMS `config.yml` file:

```yaml
backend:
name: github
repo: owner-name/repo-name # Path to your Github repository
```

### External OAuth Clients
## GitLab Backend

If you would like to facilitate your own OAuth authentication rather than use Netlify's service, you
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.

Unlike GitHub, the GitLab API allows for two types of OAuth2 flows: [Web Application Flow](https://docs.gitlab.com/ce/api/oauth2.html#web-application-flow), which works much like the GitHub OAuth flow described above, and [Implicit Grant](https://docs.gitlab.com/ce/api/oauth2.html#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](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) 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](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider) to add your new GitLab Application ID and Secret to your Netlify site dashboard.
2. In your repository, add the following lines to your Netlify CMS `config.yml` file:

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

### Client-Side Implicit Grant

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

1. Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html#adding-an-application-through-the-profile) 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 will give you an **Application ID**. Copy this and enter it in your Netlify CMS `config.yml` file, along with the following settings:

```yaml
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:

```yaml
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 that in both cases, GitLab will also provide you with a client secret. You should _never_ store this in your repo or reveal it in the client.

## Bitbucket Support

Netlify CMS is meant to be platform agnostic, so we’re always looking to expand the ecosystem and
find new ways to use it. Check out our active PR in progress for
[Bitbucket](https://github.com/netlify/netlify-cms/pull/525) backend support.

Git Gateway could also be modified to support other Git hosts. If you're interested, you can file an
issue (or a pull request!) in the [git-gateway repo](https://github.com/netlify/git-gateway).

## External OAuth Clients

If you would like to facilitate your own OAuth authentication rather than use Netlify's service or implicit grant, you
can use one of the community-maintained projects below. Feel free to [submit a pull request](https://github.com/netlify/netlify-cms/blob/master/CONTRIBUTING.md) if you'd like to add yours!

| Author | Supported Git hosts | Language(s)/Platform(s) | Link |
Expand All @@ -74,28 +135,18 @@ can use one of the community-maintained projects below. Feel free to [submit a p

Check each project's documentation for instructions on how to configure it.

## Bitbucket and GitLab Support

Netlify CMS is meant to be platform agnostic, so we’re always looking to expand the ecosystem and
find new ways to use it. Check out our active PRs in progress for
[Bitbucket](https://github.com/netlify/netlify-cms/pull/525) and
[Gitlab](https://github.com/netlify/netlify-cms/pull/517) backends.

Git Gateway could also be modified to support these Git hosts. If you're interested, you can file an
issue (or a pull request!) in the [git-gateway repo](https://github.com/netlify/git-gateway).

## Options

Both `git-gateway` and `github` backends allow some additional optional fields for certain use
The `git-gateway`, `github`, and `gitlab` backends all allow some additional optional fields for certain use
cases. A full reference is below. Note that these are properties of the `backend` field, and should
be nested under that field.

| Field | Default | Description |
| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repo` | none | **Required** for `github` backend; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. |
| `repo` | none | **Required** for `github` and `gitlab` backends; ignored by `git-gateway`. Follows the pattern `[org-or-username]/[repo-name]`. |
| `accept_roles` | none | `git-gateway` only. Limits CMS access to your defined array of user roles. Omitting this field gives access to all registered users. |
| `branch` | `master` | The branch where published content is stored. All CMS commits and PRs are made to this branch. |
| `api_root` | `https://api.github.com` (ignored for `git-gateway` backend) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise. |
| `api_root` | `https://api.github.com` (GitHub) or `https://gitlab.com/api/v4` (GitLab) | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. |
| `site_domain` | `location.hostname` (or `cms.netlify.com` when on `localhost`) | Sets the `site_id` query param sent to the API endpoint. Non-Netlify auth setups will often need to set this for local development to work properly. |
| `base_url` | `https://api.netlify.com` | OAuth client URL for the `github` backend. **Required** when using an external OAuth server with the `github` backend. |
| `auth_endpoint` | `auth` | Path to append to `base_url` for authentication requests. Optional. |
| `base_url` | `https://api.netlify.com` (GitHub) or `https://gitlab.com` (GitLab) | OAuth client URL. **Required** when using an external OAuth server or self-hosted GitLab. |
| `auth_endpoint` | `auth` (GitHub) or `oauth/authorize` (GitLab) | Path to append to `base_url` for authentication requests. Optional. |
Loading

0 comments on commit b47bb66

Please sign in to comment.