Confusion around setting up Git Gateway + Identity for use in Decap CMS

[jeremyzilar]

related decaporg/decap-cms#3711

---

I am in the process of installing NetlifyCMS + Netlify Large Media and wanted to log a bit of confusion I am encountering in the docs around the git-gateway setup.

My path

1. I started on the NetlifyCMS page for setting up Netlify Large Media
2. On the second requirement, I navigated to Configure Netlify CMS to use the Git Gateway backend with Netlify Identity
3. From the Git Gateway page, I then went to the Netlify Identity Docs
4. Then I noticed that it mentioned using the netlify-identity-widget to integrate the into your site, but was not sure if it was already included in the NetlifyCMS JS and set up, since this was not mentioned in any of the previous docs for setting up NetlifyCMS + Large Media + Git Gateway.
5. Also, in looking at the code samples on the Netlify Identity Widget README, it looked like this was the code we'd use to should need to put a login button on the public facing side of our site. The readme didn't mention NetlifyCMS or indicate if this would go in the /admin/index.html page for NetlifyCMS. So I skipped this step, knowing that I could come back to it later.
6. Next, I changed the backend setting in our config to use name: git-gateway and enabled "Identity" in the Netlify admin. Then I
   • I went to our page at https://brooklynrail.netlify.app/workflow
   • "Signed up" for an account
   • received an email with a link to authenticate
   • clicked the link to authenticate
   • verified that my account was created in the Netlify Identity Admin ✅
   • tried to log in using the new account I set up https://brooklynrail.netlify.app/workflow and got "Email not confirmed" 🛑

Wrong turn, going back

So now I am going back to installing the Netlify Identity Widget in our CMS admin page, and have a few questions about the code on the readme:

1. Of the code that is here, what is the minimum that I need to install on my page for NetlifyCMS?
2. The example of the global object, is that needed in my site, or is that just an example?
3. Do I need to configure "roles" to get this working?

---

Recommendations for adding Clarity in the docs

I am taking some notes locally and am happy to submit a PR when this is all done. Here are some initial thoughts on improvements

1. Include all of the steps for configuring up Netlify Large Media on the main docs page,
2. include the steps to set up Git Gateway and Identity and Identity Widget
3. include each of the command line installs that are needed as part of the steps (e.g. netlify-cli)
4. Include screenshots at each step to make it clear you're in the right place
5. Include a link to an example repo with the configuration already set up

❤️🌈

[suetorres]

Have you tried this: https://answers.netlify.com/t/common-issue-netlify-cms-git-gateway-email-not-confirmed/10690 works for me. And try switching your branch in config.yml from master to main.

[aentwist]

That answer bridged the gap in the documentation for me - the last piece of the Netlify Identity widget authentication flow. It led me to the actual documentation, which does document a particular case although without explanation, that being: 1. Netlify free plan => cannot change email templates to change URLs to /admin => additionally add the Identity widget to the site root. I do not like where this is placed in the documentation. It is buried under Add to Your Site > Authentication instead of just Git Gateway. Furthermore, it does not provide explanation, or document 2. Netlify paid plan => change email templates.

[sterlingwes]

For those using a simple GitHub backend and wanting lightweight auth I've added a docs section that might help with the same confusion I had: #64