From 29d1b9f67f31ef63af7853293098ed9d5ee64f09 Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Thu, 7 Jun 2018 19:24:42 -0700 Subject: [PATCH 1/9] Update Authentication doc to include GitLab --- .../content/docs/authentication-backends.md | 73 ++++++++++++++++--- 1 file changed, 61 insertions(+), 12 deletions(-) diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index 2d783dc6fb71..ae89f8f75f4b 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -7,13 +7,13 @@ 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 provider, 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: @@ -41,8 +41,7 @@ To configure in Netlify CMS, use the same `backend` settings in your `config.yml ## 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 the user's GitHub account 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 @@ -74,28 +73,78 @@ 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 +## GitLab Backend + +For repositories stored on GitLab, the `gitlab` backend allows CMS users to log in directly with their GitLab account. Note that the user's GitLab account 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 `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 `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` and `auth_url` 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 + auth_url: https://my-hosted-gitlab-instance.com/oauth/authorize + ``` + +## 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 PRs in progress for -[Bitbucket](https://github.com/netlify/netlify-cms/pull/525) and -[Gitlab](https://github.com/netlify/netlify-cms/pull/517) backends. +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 these Git hosts. If you're interested, you can file an +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). ## 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); ignored for `git-gateway` | 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. | +| `auth_url` | `https://gitlab.com/oauth/authorize` on `gitlab` backend; ignored by `github` and `git-gateway` | Authentication endpoint URL. **Required** for implicit grant on self-hosted GitLab | From 4ea655ce336b354b4aedf7f75900161a7cc13235 Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Thu, 7 Jun 2018 19:25:30 -0700 Subject: [PATCH 2/9] Update GitHub-only statements sitewide --- website/site/content/docs/add-to-your-site.md | 8 ++++---- website/site/content/docs/beta-features.md | 3 ++- website/site/content/docs/intro.md | 4 ++-- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/website/site/content/docs/add-to-your-site.md b/website/site/content/docs/add-to-your-site.md index 608a5e66d10c..9a8cf2f0c364 100755 --- a/website/site/content/docs/add-to-your-site.md +++ b/website/site/content/docs/add-to-your-site.md @@ -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/). (Bitbucket support [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). @@ -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: +Because we're using [Netlify](https://www.netlify.com) for our hosting and authentication, backend configuration is fairly strightforward. You can start your `config.yml` file with these lines: ```yaml backend: @@ -226,12 +226,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 provider 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 provider 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 diff --git a/website/site/content/docs/beta-features.md b/website/site/content/docs/beta-features.md index b0cb86af1633..b7868d2d60eb 100644 --- a/website/site/content/docs/beta-features.md +++ b/website/site/content/docs/beta-features.md @@ -81,7 +81,7 @@ CMS.registerPreviewStyle(styles.toString(), { raw: true }) ``` ## Squash merge GitHub pull requests -When using the [Editorial Workflow](/docs/configuration-options/#publish-mode) with the `github` or `git-gateway` backends, Netlify CMS creates a pull request for each unpublished entry. Every time the unpublished entry is changed and saved, a new commit is added to the pull request. When the entry is published, the pull request is merged, and all of those commits are added to your project commit history in a merge commit. +When using the [Editorial Workflow](/docs/configuration-options/#publish-mode) with the `github` or GitHub-connected `git-gateway` backends, Netlify CMS creates a pull request for each unpublished entry. Every time the unpublished entry is changed and saved, a new commit is added to the pull request. When the entry is published, the pull request is merged, and all of those commits are added to your project commit history in a merge commit. The squash merge option causes all commits to be "squashed" into a single commit when the pull request is merged, and the resulting commit is rebased onto the target branch, avoiding the merge commit altogether. @@ -91,6 +91,7 @@ To enable this feature, you can set the following option in your `config.yml`: backend: squash_merges: true ``` + ## Commit Message Templates You can customize the templates used by Netlify CMS to generate commit messages by setting the `commit_messages` option under `backend` in your `config.yml`. diff --git a/website/site/content/docs/intro.md b/website/site/content/docs/intro.md index 447ccfec7696..d987d60b2556 100755 --- a/website/site/content/docs/intro.md +++ b/website/site/content/docs/intro.md @@ -10,12 +10,12 @@ menu: Netlify CMS is an open source content management system for your Git workflow that enables you to provide editors with friendly UI and intuitive workflow. You can use it with any static site generator to create faster, more flexible web projects. Content is stored in your Git repository alongside your code for easier versioning, multi-channel publishing, and the option to handle content updates directly in Git. -At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub API. This provides many advantages, including: +At its core, Netlify CMS is an open-source React app that acts as a wrapper for the Git workflow, using the GitHub or GitLab API. This provides many advantages, including: * **Fast, web-based UI:** with rich-text editing, real-time preview, and drag-and-drop media uploads. * **Platform agnostic:** works with most static site generators. * **Easy installation:** add two files to your site and hook up the backend by including in your build process or linking to our CDN. -* **Modern authentication:** using GitHub and JSON web tokens. +* **Modern authentication:** using GitHub or GitLab and JSON web tokens. * **Flexible content types:** specify an unlimited number of content types with custom fields. * **Fully extensible:** create custom-styled previews, UI widgets, and editor plugins. From 0a3c665e4a6d07628881fa40f74986c2ec69b6ad Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Fri, 8 Jun 2018 19:09:18 -0700 Subject: [PATCH 3/9] Updates based on comments --- website/site/content/docs/add-to-your-site.md | 6 ++-- .../content/docs/authentication-backends.md | 32 ++++++++++--------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/website/site/content/docs/add-to-your-site.md b/website/site/content/docs/add-to-your-site.md index 9a8cf2f0c364..b1533de22eac 100755 --- a/website/site/content/docs/add-to-your-site.md +++ b/website/site/content/docs/add-to-your-site.md @@ -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/) or [GitLab](https://about.gitlab.com/). (Bitbucket support [coming soon](https://github.com/netlify/netlify-cms/pull/525).) +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). @@ -226,12 +226,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 an account with your Git provider 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 your Git provider 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/). +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 diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index ae89f8f75f4b..08c0a78842ab 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -41,7 +41,7 @@ To configure in Netlify CMS, use the same `backend` settings in your `config.yml ## GitHub Backend -For repositories stored on GitHub, 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 @@ -59,20 +59,6 @@ To enable it: repo: owner-name/repo-name # Path to your Github repository ``` -### External OAuth Clients - -If you would like to facilitate your own OAuth authentication rather than use Netlify's service, 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 | -| ---------------------------------------------- | ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| [@vencax](https://github.com/vencax) | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) | -| [@igk1972](https://github.com/igk1972) | GitHub, GitHub Enterprise | Go | [Repo](https://github.com/igk1972/netlify-cms-oauth-provider-go) | -| [@davidejones](https://github.com/davidejones) | GitHub, GitHub Enterprise | Python | [Repo](https://github.com/davidejones/netlify-cms-oauth-provider-python) | -| [@marksteele](https://github.com/marksteele) | GitHub, GitHub Enterprise | Serverless | [Repo](https://github.com/marksteele/netlify-serverless-oauth2-backend), [Blog](https://www.control-alt-del.org/blog/serverless-blog-howto/) | - -Check each project's documentation for instructions on how to configure it. - ## GitLab Backend For repositories stored on GitLab, the `gitlab` backend allows CMS users to log in directly with their GitLab account. Note that the user's GitLab account must have push access to your content repository for this to work. @@ -123,6 +109,8 @@ With GitLab's Implicit Grant, users can authenticate with GitLab directly from t auth_url: https://my-hosted-gitlab-instance.com/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 @@ -132,6 +120,20 @@ find new ways to use it. Check out our active PR in progress for 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 | +| ---------------------------------------------- | ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| [@vencax](https://github.com/vencax) | GitHub, GitHub Enterprise | Node.js | [Repo](https://github.com/vencax/netlify-cms-github-oauth-provider) | +| [@igk1972](https://github.com/igk1972) | GitHub, GitHub Enterprise | Go | [Repo](https://github.com/igk1972/netlify-cms-oauth-provider-go) | +| [@davidejones](https://github.com/davidejones) | GitHub, GitHub Enterprise | Python | [Repo](https://github.com/davidejones/netlify-cms-oauth-provider-python) | +| [@marksteele](https://github.com/marksteele) | GitHub, GitHub Enterprise | Serverless | [Repo](https://github.com/marksteele/netlify-serverless-oauth2-backend), [Blog](https://www.control-alt-del.org/blog/serverless-blog-howto/) | + +Check each project's documentation for instructions on how to configure it. + ## Options The `git-gateway`, `github`, and `gitlab` backends all allow some additional optional fields for certain use From 163bb78359530834e99a544326e76ad32f02ff7c Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Sun, 10 Jun 2018 12:00:40 -0700 Subject: [PATCH 4/9] Clarify which config.yml in auth doc --- website/site/content/docs/authentication-backends.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index 08c0a78842ab..0f39c337e75b 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -19,7 +19,7 @@ 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: @@ -30,14 +30,14 @@ 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 @@ -51,7 +51,7 @@ 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: @@ -74,7 +74,7 @@ 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 `config.yml` file: +2. In your repository, add the following lines to your Netlify CMS `config.yml` file: ```yaml backend: @@ -87,7 +87,7 @@ To enable it: 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 `config.yml` file, along with the following settings: +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: From 53283d31de4636371794d6ec160aeaa3327282fb Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Sun, 10 Jun 2018 12:06:38 -0700 Subject: [PATCH 5/9] Clarify which config.yml in all docs --- website/site/content/docs/add-to-your-site.md | 6 +++--- website/site/content/docs/beta-features.md | 8 ++++---- website/site/content/docs/configuration-options.md | 8 ++++---- website/site/content/docs/widgets/index.md | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/website/site/content/docs/add-to-your-site.md b/website/site/content/docs/add-to-your-site.md index b1533de22eac..1276ed403fe9 100755 --- a/website/site/content/docs/add-to-your-site.md +++ b/website/site/content/docs/add-to-your-site.md @@ -80,7 +80,7 @@ Configuration will be different for every site, so we'll break it down into part ### Backend -Because we're using [Netlify](https://www.netlify.com) for our hosting and authentication, backend configuration is fairly strightforward. You can start your `config.yml` file with these lines: +Because we're using [Netlify](https://www.netlify.com) for our hosting and authentication, backend configuration is fairly strightforward. You can start your Netlify CMS `config.yml` file with these lines: ```yaml backend: @@ -92,7 +92,7 @@ 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`: +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 @@ -198,7 +198,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 diff --git a/website/site/content/docs/beta-features.md b/website/site/content/docs/beta-features.md index b7868d2d60eb..3cb25b548555 100644 --- a/website/site/content/docs/beta-features.md +++ b/website/site/content/docs/beta-features.md @@ -20,7 +20,7 @@ as `nc-root`. If Netlify CMS finds an element with this ID during initialization within that element instead of creating it's own. ## Manual Initialization -Netlify CMS can now be manually initialized, rather than automatically loading up the moment you import it. The whole point of this at the moment is to inject configuration into Netlify CMS before it loads, bypassing need for an actual config.yml. This is important, for example, when creating tight integrations with static site generators. +Netlify CMS can now be manually initialized, rather than automatically loading up the moment you import it. The whole point of this at the moment is to inject configuration into Netlify CMS before it loads, bypassing need for an actual Netlify CMS `config.yml`. This is important, for example, when creating tight integrations with static site generators. Injecting config is technically already possible by setting `window.CMS_CONFIG` before importing/requiring/running Netlify CMS, but most projects are modular and don't want to use globals, plus `window.CMS_CONFIG` is an internal, not technically supported, and provides no validation. @@ -85,7 +85,7 @@ When using the [Editorial Workflow](/docs/configuration-options/#publish-mode) w The squash merge option causes all commits to be "squashed" into a single commit when the pull request is merged, and the resulting commit is rebased onto the target branch, avoiding the merge commit altogether. -To enable this feature, you can set the following option in your `config.yml`: +To enable this feature, you can set the following option in your Netlify CMS `config.yml`: ```yaml backend: @@ -93,11 +93,11 @@ backend: ``` ## Commit Message Templates -You can customize the templates used by Netlify CMS to generate commit messages by setting the `commit_messages` option under `backend` in your `config.yml`. +You can customize the templates used by Netlify CMS to generate commit messages by setting the `commit_messages` option under `backend` in your Netlify CMS `config.yml`. Template tags wrapped in curly braces will be expanded to include information about the file changed by the commit. For example, `{{path}}` will include the full path to the file changed. -Setting up your `config.yml` to recreate the default values would look like this: +Setting up your Netlify CMS `config.yml` to recreate the default values would look like this: ```yaml backend: diff --git a/website/site/content/docs/configuration-options.md b/website/site/content/docs/configuration-options.md index 1b8407b2f5dc..c8db9009ad3c 100644 --- a/website/site/content/docs/configuration-options.md +++ b/website/site/content/docs/configuration-options.md @@ -8,7 +8,7 @@ menu: # Configuration Options -All configuration options for Netlify CMS are specified in the `config.yml` file, in the folder where you access the editor UI (usually in the `/admin` folder). +All configuration options for Netlify CMS are specified in a `config.yml` file, in the folder where you access the editor UI (usually in the `/admin` folder). Alternatively, you can specify a custom config file using a link tag: @@ -36,7 +36,7 @@ By default, all entries created or edited in the Netlify CMS are committed direc The `publish_mode` option allows you to enable "Editorial Workflow" mode for more control over the content publishing phases. All unpublished entries will be arranged in a board according to their status, and they can be further reviewed and edited before going live. -You can enable the Editorial Workflow with the following line in `config.yml`: +You can enable the Editorial Workflow with the following line in your Netlify CMS `config.yml` file: ```yaml publish_mode: editorial_workflow @@ -104,7 +104,7 @@ slug: *This setting is required.* -The `collections` setting is the heart of your Netlify CMS configuration, as it determines how content types and editor fields in the UI generate files and content in your repository. Each collection you configure displays in the left sidebar of the Content page of the editor UI, in the order they are entered into `config.yml`. +The `collections` setting is the heart of your Netlify CMS configuration, as it determines how content types and editor fields in the UI generate files and content in your repository. Each collection you configure displays in the left sidebar of the Content page of the editor UI, in the order they are entered into your Netlify CMS `config.yml` file. `collections` accepts a list of collection objects, each with the following options: @@ -167,7 +167,7 @@ slug: "{{year}}-{{month}}-{{day}}_{{slug}}" ### `fields` -The `fields` option maps editor UI widgets to field-value pairs in the saved file. The order of the fields in `config.yml` determines their order in the editor UI and in the saved file. +The `fields` option maps editor UI widgets to field-value pairs in the saved file. The order of the fields in your Netlify CMS `config.yml` file determines their order in the editor UI and in the saved file. `fields` accepts a list of collection objects, each with the following options: diff --git a/website/site/content/docs/widgets/index.md b/website/site/content/docs/widgets/index.md index 635c2c509936..a36323531bf9 100644 --- a/website/site/content/docs/widgets/index.md +++ b/website/site/content/docs/widgets/index.md @@ -10,7 +10,7 @@ menu: Widgets define the data type and interface for entry fields. Netlify CMS comes with several built-in widgets. Click the widget names in the sidebar to jump to specific widget details. We’re always adding new widgets, and you can also [create your own](https://www.netlifycms.org/docs/custom-widgets)! -Widgets are specified as collection fields in the `config.yml` file. Note that [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components) allows lists and objects to be written in block or inline style, and the code samples below include a mix of both. +Widgets are specified as collection fields in the Netlify CMS `config.yml` file. Note that [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components) allows lists and objects to be written in block or inline style, and the code samples below include a mix of both. To see working examples of all of the built-in widgets, try making a 'Kitchen Sink' collection item on the [CMS demo site](https://cms-demo.netlify.com). (No login required: click the login button and the CMS will open.) You can refer to the demo [configuration code](https://github.com/netlify/netlify-cms/blob/master/example/config.yml#L60) to see how each field was configured. From b20b7cef6af3b4cd62448c98bb1fb80f3a0abef9 Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Sun, 10 Jun 2018 12:09:50 -0700 Subject: [PATCH 6/9] Add GitLab option to Deploy to Netlify guide --- website/site/content/docs/start-with-a-template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/site/content/docs/start-with-a-template.md b/website/site/content/docs/start-with-a-template.md index 322f10b1ab53..e6f4f31f0b74 100644 --- a/website/site/content/docs/start-with-a-template.md +++ b/website/site/content/docs/start-with-a-template.md @@ -21,7 +21,7 @@ Netlify CMS can be [added to an existing site](https://www.netlifycms.org/docs/a -After clicking one of those buttons, you’ll authenticate with GitHub and choose a repository name. Netlify will then automatically create a repository in your GitHub account with a copy of the files from the template. Next, it will build and deploy the new site on Netlify, bringing you to the site dashboard when the build is complete. +After clicking one of those buttons, you’ll authenticate with GitHub or GitLab and choose a repository name. Netlify will then automatically create a clone of the repository in your GitHub or GitLab account. Next, it will build and deploy the new site on Netlify, bringing you to the site dashboard when the build is complete. ## Access Netlify CMS on your new site @@ -36,7 +36,7 @@ After clicking one of those buttons, you’ll authenticate with GitHub and choos 3. Enter a password, sign in, and you’ll be directed straight to the CMS. (For future visits, you can go straight to `/admin/`.) -Try adding and editing posts, or changing the content of the Products page. When you save, the changes will be pushed immediately to GitHub, triggering a build on Netlify, and updating the content on your site. Check out the configuration code by visiting your site repo. +Try adding and editing posts, or changing the content of the Products page. When you save, the changes will be pushed immediately to your Git repository, triggering a build on Netlify, and updating the content on your site. Check out the configuration code by visiting your site repo. ## More paths to explore From c0a874a15d1c2c44e7f72e81564dedee59aaa95c Mon Sep 17 00:00:00 2001 From: Caleb Date: Sat, 9 Jun 2018 13:42:31 -0600 Subject: [PATCH 7/9] Update authentication-backends.md --- website/site/content/docs/authentication-backends.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index 0f39c337e75b..82a9a11d1d5a 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -61,7 +61,7 @@ To enable it: ## GitLab Backend -For repositories stored on GitLab, the `gitlab` backend allows CMS users to log in directly with their GitLab account. Note that the user's GitLab account must have push access to your content repository for this to work. +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. From 1363c09bc474a9362264d02a2bc10357789de34f Mon Sep 17 00:00:00 2001 From: Jessica Parsons Date: Mon, 11 Jun 2018 15:22:37 -0700 Subject: [PATCH 8/9] Switch from `auth_url` to `base_url`/`auth_endpoint` --- website/site/content/docs/authentication-backends.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index 82a9a11d1d5a..3ed7659b2c01 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -97,7 +97,7 @@ With GitLab's Implicit Grant, users can authenticate with GitLab directly from t 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` and `auth_url` fields: + 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: @@ -106,7 +106,8 @@ With GitLab's Implicit Grant, users can authenticate with GitLab directly from t 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 - auth_url: https://my-hosted-gitlab-instance.com/oauth/authorize + 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. @@ -145,8 +146,7 @@ be nested under that field. | `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` (GitHub) or `https://gitlab.com/api/v4` (GitLab); ignored for `git-gateway` | The API endpoint. Only necessary in certain cases, like with GitHub Enterprise or self-hosted GitLab. | +| `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. | -| `auth_url` | `https://gitlab.com/oauth/authorize` on `gitlab` backend; ignored by `github` and `git-gateway` | Authentication endpoint URL. **Required** for implicit grant on self-hosted GitLab | +| `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. | From 7db2b112735948b4ec76cee5d242b87413e90471 Mon Sep 17 00:00:00 2001 From: Shawn Erquhart Date: Tue, 12 Jun 2018 09:31:29 -0400 Subject: [PATCH 9/9] update docs --- website/site/content/docs/add-to-your-site.md | 6 ++++-- website/site/content/docs/authentication-backends.md | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/website/site/content/docs/add-to-your-site.md b/website/site/content/docs/add-to-your-site.md index 1276ed403fe9..79d5f6ee2d3e 100755 --- a/website/site/content/docs/add-to-your-site.md +++ b/website/site/content/docs/add-to-your-site.md @@ -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/) 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)) +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). @@ -80,7 +80,7 @@ Configuration will be different for every site, so we'll break it down into part ### Backend -Because we're using [Netlify](https://www.netlify.com) for our hosting and authentication, backend configuration is fairly strightforward. You can start your Netlify CMS `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: @@ -92,6 +92,8 @@ These lines specify your backend protocol and your publication branch. Git Gatew ### Editorial Workflow +**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 diff --git a/website/site/content/docs/authentication-backends.md b/website/site/content/docs/authentication-backends.md index 3ed7659b2c01..5ff302fce5b6 100644 --- a/website/site/content/docs/authentication-backends.md +++ b/website/site/content/docs/authentication-backends.md @@ -7,7 +7,7 @@ menu: --- # Authentication & Backends -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 provider, and in most cases 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.