Add GitLab backend to docs #1413

verythorough · 2018-06-08T02:43:52Z

- Summary
Updates docs to go with the addition of the GitLab backend! 🎉

- Test plan
Most of the changes can be found on
https://docs-update-gitlab--netlify-cms-www.netlify.com/docs/authentication-backends/

If someone who hasn't built the thing or written the doc could run through the instructions for Git Gateway and GitLab backends, that would be 👌

- A picture of a cute animal (not mandatory but encouraged)

verythorough · 2018-06-08T02:45:36Z

Deploy preview for netlify-cms-www ready!

Built with commit 7db2b11

https://deploy-preview-1413--netlify-cms-www.netlify.com

verythorough · 2018-06-08T02:48:00Z

Deploy preview for cms-demo ready!

Built with commit 7db2b11

https://deploy-preview-1413--cms-demo.netlify.com

Kaligule · 2018-06-08T05:24:28Z

website/site/content/docs/add-to-your-site.md

@@ -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:


I suggest "Git hoster" instead of "Git provider". The value of these services is the hosting they do for you, not that they enable you tu use git.

Yeah, I always struggle between "Git provider" and "Git host." Your argument makes sense.

Thanks for reviewing!

Kaligule · 2018-06-08T05:24:59Z

website/site/content/docs/add-to-your-site.md


 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/).


Same as above. I suggest "Git hoster" instead of "Git provider".

Kaligule · 2018-06-08T05:43:08Z

I have looked over the changes. I commented a few suggestions where to improve, but I think the documentation is helpfull and could be merged even without going into those. 👍

Disclaimer though:

I never worked activly with netlify before, so I might be missing something.
I am not a native speaker.
I haven't tried out the new backend, just proofread the doku.

Thank you for your great work.

tech4him1

Looks awesome Jessica, just a few comments.

tech4him1 · 2018-06-08T14:29:51Z

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).)


Maybe we should also note that it is possible to use/create a custom backend.

Oh, good point!

Of course, it sure would be nice if we had a doc we could link to about how to make a custom backend... 😉

You know what, I think you would be the perfect person to write that! 😉

tech4him1 · 2018-06-08T14:35:39Z

website/site/content/docs/authentication-backends.md

+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:


Let's note that you should never put your Secret in the docs, only the App ID.

tech4him1 · 2018-06-08T14:37:58Z

website/site/content/docs/authentication-backends.md

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


@erquhart @Benaiah @talves Should we split this into base_url and auth_endpoint to be consistent with the other backends?

tech4him1 · 2018-06-08T14:38:25Z

website/site/content/docs/authentication-backends.md

@@ -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.


Just reading this sounds like we repeat the word "GitHub" too much, but maybe it's necessary for disambiguation of what account the user is dealing with. 😄

Perhaps we could replace

Note that the user's GitHub account ...

with

Note that the account ...

That would reduce the repetition and still very explicit.

Heh, yeah. I think maybe we could remove the last "GitHub" and have it still be clear enough.

tech4him1 · 2018-06-08T14:40:29Z

website/site/content/docs/authentication-backends.md

@@ -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.


Should the "External OAuth Clients" section be moved below GitLab, or stay here? I'm guessing most people would just use implicit OAuth with GitLab anyway, but there are possible security benefits of using the full flow.

Yeah, I was wondering about that, too, or about adding a similar subsection in the gitlab backend section. Seeing that the table does include a column for Git host support, I suppose the section really can work generally across hosts/backends, and the setup details are on the individual project repos, so need to worry about that aspect of the content.

OK, done thinking in type. Gonna move it. 😛

verythorough · 2018-06-09T02:31:27Z

I've updated things in response to comments. The only remaining question is whether the auth_url setting should be broken into base_url and auth_endpoint to match existing implementations.

verythorough · 2018-06-09T02:37:55Z

Oh! And as of a few minutes ago, GitLab repos are now supported for Deploy to Netlify buttons. It would be cool to add GitLab versions of each of the templates featured on https://www.netlifycms.org/docs/start-with-a-template/

Does anyone have GitLab versions of these repos set up that we could use for the buttons?

tech4him1 · 2018-06-09T19:46:22Z

@verythorough GitLab has a feature to mirror a repository from GitHub and keep them in sync. Maybe we could set up a netlify-templates group on GitLab as well, and just mirror some of the repos for now? The link in the README would have to be different, though, so maybe we have to fork it instead of syncing?

erquhart · 2018-06-09T21:12:16Z

These Deploy to Netlify templates use Git Gateway, we shouldn't maintain separate versions for different providers. The only difference between them would be where the template is hosted, which shouldn't matter.

Kaligule · 2018-06-08T05:33:20Z

website/site/content/docs/authentication-backends.md

+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:


Just to be sure: This is the config for netlify, not for the static site generator or the gitlab-CI. Perhaps we could be a bit more specific here.

Very good point, especially since Jekyll uses the filename of config.yml as well. Maybe

add the following lines to your Netlify CMS config.yml file

Updated throughout the auth doc, then went ahead and did it for all the docs. :)

Kaligule · 2018-06-08T16:39:32Z

website/site/content/docs/authentication-backends.md

@@ -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.


Perhaps we could replace

Note that the user's GitHub account ...

with

Note that the account ...

That would reduce the repetition and still very explicit.

verythorough · 2018-06-10T18:52:27Z

At the time I mentioned having separate GitLab-repo buttons, the Deploy to Netlify flow was relying on the location of the source repo to determine where to store the clone, which would railroad some users into GitHub if the source repos were on GitHub. However, @imorente made a change that gives users more control, removing the need for multiple buttons with different providers.

verythorough · 2018-06-10T19:15:52Z

The change above has been merged in Netlify, so users will always have the choice to clone to GitHub or GitLab, regardless of the source repo location. 🎉

I added some text to the "Start from a Template" description to include GitLab as a destination option when clicking the button.

Only question remaining is the auth_url question.

tech4him1 · 2018-06-11T18:23:14Z

@verythorough Great, that's the best option in my opinion.

tech4him1 · 2018-06-12T00:18:05Z

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 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 Netlify CMS `config.yml` file with these lines:


Maybe this should be changed to "If we are using Netlify for our hosting", since it's not required.

Please also fix strightforward => straightforward while you're at it :)

tech4him1 · 2018-06-12T00:19:00Z

website/site/content/docs/authentication-backends.md

@@ -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 provider, and in most cases that requires a server. We have a few options for handling this.


this still says "provider" (not a big deal).

tech4him1

Awesome, thanks for your work on this!

erquhart

Fantastic work @verythorough, thank you! Just a couple small things and this is ready to go.

erquhart · 2018-06-12T01:42:37Z

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/). (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))


Needs a period at end of paragraph.

erquhart · 2018-06-12T01:48:01Z

website/site/content/docs/add-to-your-site.md

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


We should now mention that editorial workflow is only currently support by GitHub and Git Gateway over GitHub.

verythorough mentioned this pull request Jun 8, 2018

GitLab backend built with cursor API #1343

Merged

12 tasks

Kaligule reviewed Jun 8, 2018

View reviewed changes

tech4him1 self-requested a review June 8, 2018 14:28

tech4him1 reviewed Jun 8, 2018

View reviewed changes

Kaligule reviewed Jun 10, 2018

View reviewed changes

tech4him1 reviewed Jun 12, 2018

View reviewed changes

tech4him1 approved these changes Jun 12, 2018

View reviewed changes

erquhart suggested changes Jun 12, 2018

View reviewed changes

erquhart changed the base branch from gitlab-benaiah-rebased-onto-cursor-api to master June 12, 2018 13:21

verythorough and others added 8 commits June 12, 2018 09:22

Update Authentication doc to include GitLab

29d1b9f

Update GitHub-only statements sitewide

4ea655c

Updates based on comments

0a3c665

Clarify which config.yml in auth doc

163bb78

Clarify which config.yml in all docs

53283d3

Add GitLab option to Deploy to Netlify guide

b20b7ce

Update authentication-backends.md

c0a874a

Switch from auth_url to base_url/auth_endpoint

1363c09

erquhart force-pushed the docs-update-gitlab branch from 8c1ca70 to 1363c09 Compare June 12, 2018 13:22

update docs

7db2b11

erquhart approved these changes Jun 12, 2018

View reviewed changes

tech4him1 approved these changes Jun 12, 2018

View reviewed changes

erquhart merged commit b47bb66 into master Jun 12, 2018

erquhart deleted the docs-update-gitlab branch June 12, 2018 13:42

erquhart pushed a commit to erquhart/netlify-cms that referenced this pull request Jun 12, 2018

Add GitLab backend to docs (decaporg#1413)

ed82020

		@@ -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.

Add GitLab backend to docs #1413

Add GitLab backend to docs #1413

Conversation

verythorough commented Jun 8, 2018

verythorough commented Jun 8, 2018 • edited Loading

verythorough commented Jun 8, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kaligule commented Jun 8, 2018

tech4him1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

verythorough commented Jun 9, 2018

verythorough commented Jun 9, 2018

tech4him1 commented Jun 9, 2018 • edited Loading

erquhart commented Jun 9, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

verythorough commented Jun 10, 2018

verythorough commented Jun 10, 2018

tech4him1 commented Jun 11, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tech4him1 left a comment

Choose a reason for hiding this comment

erquhart left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

verythorough commented Jun 8, 2018 •

edited

Loading

verythorough commented Jun 8, 2018 •

edited

Loading

tech4him1 commented Jun 9, 2018 •

edited

Loading