To use decap CMS on Github pages. Do I have to host the site on Netlify?

[RDjarbeng]

Describe the bug
I followed the jekyll setup instructions and my site still can't use decap CMS. I followed the instructions here
jekyll guide and here- GitHub backend to setup the GitHub backend.

I followed the steps to setup the identity widget
I have setup the secrets and got the client ID for my project but at the section that says to:

Follow the authentication provider setup steps in the Netlify docs

It says in the netlify docs

When you complete application registration with GitHub, you need to add the Client ID and Client Secret to your Netlify site:

Problem is that the site isn't hosted on Netlify, since it's on Github pages. I assumed I wouldn't have to change the hosting provider. But the remaining steps require a Netlify site to do these steps in the Netlify UI page. Clicking the links takes me to one of my other projects hosted on Netlify so I can enter the client ID and secret.

Go to Site configuration > Access & security > OAuth
Under Authentication Providers, select Install Provider.
Select GitHub and enter the Client ID and Client Secret from earlier, then save.

So this is where I had to stop following the tutorial on the DecapCMS docs. I feel I'm almost there but just missing something.

I tried to look for alternatives and found the section for external OAuth, but it doesn't have a jekyll setup with Github pages
[https://decapcms.org/docs/external-oauth-clients/](external OAuth)

Nevertheless I tried the serverless option and it just confused me more. If anyone knows how to use this I will be grateful for your help.

To Reproduce

Expected behavior

To be able to use Decap CMS on my Github pages website without changing hosting providers

Screenshots

This is what I see when I go to the /admin route.

Then it fails at this step

Applicable Versions:

• Decap CMS version:
• decap-cms-app 3.3.3
  decap-cms.js:sourcemap:393 decap-cms-core 3.4.2
  decap-cms.js:sourcemap:491 decap-cms 3.3.3
• Git provider: GitHub
• OS: Windows 11
• Browser version Version 128.0.6613.138 (Official Build) (64-bit)

CMS configuration

https://github.com/RDjarbeng/RDjarbeng/blob/main/admin/config.yml

Additional context

Site is my personal website located at:

https://rdjarbeng.github.io/RDjarbeng/
On GitHub:

https://github.com/RDjarbeng/RDjarbeng

[RDjarbeng]

Update (21st September): I've hosted the site on netlify now and managed to get the CMS admin page up and running.

I still don't like that I have to do this, because it gives me 2 sites to work with; the one on GitHub pages and the one on Netlify. The admin route on the site on github pages is not working. Shows this page with error:

Unable to access identity settings. When using git-gateway backend make sure to enable Identity service and Git Gateway.

I read that you can push to netlify and disable builds just so you can use the authentication to sign in. This would mean you only use netlify for the initial setup. But that doesn't work. Once you disable builds you can't push any changes to the collections on the admin console (eg: modifying the config.json) unless you enable the builds.

So now if I want to continue using decap cms I have to switch between two sites; netlify for the cms, github pages for the actual website instead of just using one site for everything.

Poor experience using this.😒

[RDjarbeng]

Why not just use Netlify?

The site settings are currently set to the options for Github. On netlify the assets folder for some reason isn't found so the site displays without css and other media.

I don't want to change hosting platforms just for a CMS☹️

[hip3r]

In short: no, netlify is not a requirement.

As it's described in docs, to use Decap cms it's not necessary to host site on netlify https://decapcms.org/docs/intro/#decap-cms-vs-netlify

The links that you followed, describe that Netlify is used for git authentication (not hosting) https://decapcms.org/docs/jekyll/#enable-authentication-for-cms-users

How to set git gateway without netlify, see https://decapcms.org/docs/git-gateway-backend/#git-gateway-without-netlify
Docs don't have example, since Decap cms allows a lot of custom implementations.
See if this helps decaporg/decap-cms#6370
If not, try asking a community.

[RDjarbeng]

The links that you followed, describe that Netlify is used for git authentication (not hosting)

Yes, but the steps shown require a site to be set up on netlify.
I think the docs missed a step where you have to setup some kind of dummy site on netlify (that doesn't necessarily contain the site code), before you can follow the rest of the steps listed there. For example:

"enable Netlify Identity and Git Gateway services for the backend, then add the Identity widget to render a login portal on the frontend." -- This won't work if you don't have a site on netlify for your project

https://decapcms.org/docs/git-gateway-backend/#git-gateway-without-netlify

This link you provided for 'git gateway without nelify' actually only has this as useful information

'You can use Git Gateway without Netlify by setting up your own Git Gateway server and connecting it with your own instance of GoTrue'

So the title is misleading. Should just be 'git gateway with netlify gotrue' since it only has one option.😒 I don't know much about gotrue but my guess is that it's gonna be a similar workload to getting decapCMS up and running.

Thanks anyway

No decaporg/decap-cms#6370 doesn't help.

[martinjagodic]

@RDjarbeng you have a point here. I think this is more of a documentation issue, so I'm transferring the issue to that repository. If you have a proposal on how we could improve, please let me know.

[hip3r]

So the title is misleading. Should just be 'git gateway with netlify gotrue' since it only has one option.😒 I don't know much about gotrue but my guess is that it's gonna be a similar workload to getting decapCMS up and running.

it also writes: or with any other identity service that can issue JSON Web Tokens (JWT). - Documentation clearly suggests that it's not the only option.

I would be also happy to see examples

[RDjarbeng]

@martinjagodic

My suggestion I can see at the moment is to specify clearly the part of the basic steps that requires a Netlify account and site to complete.

Suggested Improvements for Decap CMS Documentation

Issue

The current documentation lacks clarity on which steps require a Netlify account and site setup, potentially causing confusion for users trying to complete the tutorial.

Specific Area for Improvement

In the basic steps, particularly number 2: Choosing a Backend

Current Situation

The documentation currently states:

Setup on Netlify

Netlify offers a built-in authentication service called Identity. In order to use it, connect your site repo with Netlify. Netlify has published a general Step-by-Step Guide for this, along with detailed guides for many popular static site generators.

This section assumes the user is setting up a static site and directs them to Netlify's guide, which may not be applicable or necessary for all users. Here is the issue, this is the problem we hope to solve.

Suggested Solutions

1. Clarify Netlify Account Requirement:

   • Add a clear statement that a Netlify account is required for this method.
   • Explain that users will need to set up a site on Netlify, even if they're not deploying a static site or single-page app just to continue following the tutorial steps.

2. Provide Alternative Authentication Options:

   • Explain that setting up a static site on Netlify is not necessary for all users.
   • Offer steps for setting up only authentication without deploying a site on Netlify.

3. Guide Users Returning from Netlify:

   • For users who have followed Netlify's guide and deployed a site:
     • Help them identify which parts of the process they completed are specific to Netlify authentication.
     • Clarify which parts do not require Netlify hosting.

4. Restructure the Documentation:

   • Create separate sections for:
     a. Users who want to use Netlify for both hosting and authentication
     b. Users who only need Netlify for authentication

Proposed Documentation Structure

2. Choosing a Backend

### Setup on Netlify

Netlify offers a built-in authentication service called Identity. To use this method:

1. **Netlify Account Requirement:**
   - You will need a Netlify account. [Sign up here](https://app.netlify.com/signup) if you don't have one.
   - Note: You don't need to deploy a full site to use Netlify for authentication.

2. **Option A: Full Netlify Setup (Hosting + Authentication)**
   - If you want to deploy your site on Netlify:
     - Follow Netlify's [Step-by-Step Guide](https://www.netlify.com/blog/2016/10/27/a-step-by-step-guide-deploying-a-static-site-or-single-page-app/)
     - After deployment, proceed to step 3.

3. **Option B: Netlify Authentication Only**
   - If you only need Netlify for authentication:
     - Create a new site in your Netlify account (without deploying)
     - Enable Identity for your site
     - [Details on enabling Identity without deployment]

4. **Configure Netlify Identity**
   - [Steps to set up Identity for your site]

5. **Add the Netlify Identity Widget**
   - [Instructions for adding the Identity widget to your site]

After completing these steps, proceed to [Configure Decap CMS](https://decapcms.org/docs/configure-decap-cms/).

This restructured documentation provides a clearer path for users, regardless of whether they're using Netlify for hosting or just for authentication.

I personally have not been able to do the rest of the steps without setting up hosting on Netlify but I hope this is a good enough suggestion.

[yajo]

I was struggling with current docs too. When you follow current docs, what is not clearly explained is that Decap won't work when browsing the static site built in github pages. Instead, it will work in the static site built by Netlify. And for it to work, you must configure it properly. In my case, builds were broken because I use mkdocs and I was missing it in a requirements.txt file.

[RDjarbeng]

My sentiments exactly @yajo

[RDjarbeng]

@hip3r also suggested asking a community

I posted this on stack overflow before that comment here: StackOverflow