Last reviewed by Netlify Support: August 2023
Netlify tries to provide flexibility and open-ended support for integrating with our platform. One of the places you have options and may need help troubleshooting is around the connection from a git-based CMS to Netlify, and handling authentication for your content editors. This guide attempts to help you understand and troubleshoot how that connection is generally made, and which parts of the experience Netlify’s Support team can help you directly with.
Setup
The general / common configuration for this setup is:
- You configure your Netlify site to deploy from a supported git provider (Azure DevOps, Bitbucket, GitHub, or GitLab)
- You configure the CMS for your content (Overview | Decap CMS | Open-Source Content Management System)
- You configure something - perhaps Site-Wide Protections, Edge Functions or Role-Based Access Control to gate access to the CMS for only authorised folks.
- You configure the CMS backend to use our managed Git Gateway service, which config is documented in more detail in this article
- Someone with administrative access to your git repository connects Git Gateway to your repository via the Netlify UI, on the Identity settings page. This is the authentication that will be used by edits of the CMS when accessed live on your Netlify site.
Then, there are two possibilities for people who will edit content. Either:
- Your content editors all have access to your git repository, and you want them all to get recorded as editors individually (triggering builds “by their own Git Provider logins”, so that their edits are Pull Requests that come from an individual). In this case you’ll want to make sure that they login with the same email address (possibly, via GitHub/GitLab authentication)
- Or your content editors do not have access to your git repository, in which case they can login via email or any method, and their commits will be attributed to the user who connected git gateway above in step 5.
Please note that if you configure the CMS to connect directly to a git provider as the backend, this is not a configuration we provide tech support for, as it will be just between the CMS and your git provider, not involving Netlify’s systems directly.
Troubleshooting
At a high level, our Support team doesn’t have access to see how your git provider is configured and most problems saving content will be an issue with the git provider connection.
The advice most people need if they are here, is that there is a “regenerate token” functionality on the Identity settings page (click “Edit Settings” to show the link) that is the most frequent “fix” for sudden problems with authentication, which usually has a root cause of team membership change by the account that configured the connection, on Netlify or at your Git provider:
However, when you instead see an error at the screen with the Netlify Identity Widget’s login dialog box showing, this is likely a problem with Identity rather than Git Gateway or the CMS.
If you can instead already see the CMS and its content, but cannot save content, then you should be looking into Git Gateway settings instead (see above advice for the usual fix).
To further distinguish between the two, You can look in your browser dev tools to find a failing call in red and if the call is to a path ending in .../.netlify/identity, you should be debugging from the Identity settings screen in our UI.
In case you can see the call is to a path ending in .../.netlify/git_gateway instead, check the status page for your git provider to ensure there are no problems, and try regenerating the token as described in step 5 above.
If you see any API calls being made directly to your git provider with an issue, you might want to troubleshoot errors with your CMS and git repo (as mentioned above, without Netlify’s help).
Caveats
- Note that the GitLab connection with Git Gateway does not work very well right now. This GitHub issue has more details.