Git Gateway
Netlify’s Git Gateway connects your site to a Git provider’s API, allowing tools such as a CMS to work with content, branches, and pull requests on your users’ behalf.
For a working example using Git Gateway with Netlify Identity service and Decap CMS that allows users to edit site content without having accounts on GitHub or GitLab, or repository write privileges, try deploying this Hugo site repository:
After selecting Deploy to Netlify above, follow the instructions for adding Identity users to the project and enable Git Gateway. Any Identity users you add will have access to edit site content with Decap CMS, without a GitHub/GitLab account or access to the repository. To access the CMS for the deployed demo site, navigate to YOUR_DEPLOYED_SITE_URL/admin/.
That’s one example of something awesome that you can do with Git Gateway. To add Git Gateway to your existing web projects, check out the instructions below.
# Requirements
If you’re using a custom domain, make sure you have HTTPS working before enabling Git Gateway on your site.
Sites using Git Gateway must have a repository available on GitHub.com or GitLab.com. Self-hosted repositories on a GitHub Enterprise Server or a GitLab self-managed instance aren’t supported.
# Setup and settings
To get started using Git Gateway on a site, first enable Identity service, then go to
, and select Enable Git Gateway. This will automatically provision your site so that Identity users have access to Git Gateway’s selected endpoints on your site’s connected GitHub.com or GitLab.com-hosted repository.
You can change the settings as follows:
- Repository: indicates which repository the Gateway will access (the site’s connected repository). Works with repositories hosted on GitHub.com or GitLab.com only. Self-hosted Git instances aren’t supported. This setting is not directly editable.
- Roles: limits Gateway access to Identity users assigned a matching role (in individual Identity user data). Accepts multiple values. Leaving this field blank will give access to all Identity users on the site.
- GitHub access token: grants permission to the linked repository. Use the link to generate a token, or you may supply your own Personal Access Token. Be sure the token is generated for a user with sufficient permission on your linked repository to perform the actions you want to pass through the Gateway.
- GitLab access token: grants permission to the linked repository. You must create a personal access token in GitLab with the necessary scopes for Git Gateway to act on users’ behalf. For example, if you set up Git Gateway to allow users to edit site content without write access to the GitLab repository or even a GitLab account, then your access token needs these scopes:
api,read_api,read_repository, andwrite_repository.
Untrusted CMS deploys
In some cases, Netlify’s Deploy Request Policy may flag deploys triggered by a CMS as ”untrusted”.
If this happens, a Team Owner will need to take action to approve the deploy and associate the non-team member with a Netlify team account before the build can start. Visit our docs on deploy permissions for more information.
# Reconnect after changing repository permissions
If you change ownership on your repository, or convert a repository from public to private, you may need to reconnect Git Gateway with proper permissions:
- Go to , select Manage repository, and then Link to a different repository. Select the same repository to relink your site to it.
- Go to to add a new API access token following the instructions in the section above.
# Troubleshoot Git Gateway connection issues with GitLab
GitLab 15.0 removed support for OAuth tokens without expiration, which can cause errors using Git Gateway. Learn more about expiring tokens in GitLab’s OAuth docs.
Use deploy notifications or collaborative Deploy Previews?
Your connection to GitLab for these features may also be impacted by the GitLab 15.0 update. Learn more about how to resolve these issues for deploy notifications or collaborative Deploy Previews.
To restore your Git Gateway connection, use a GitLab personal access token (PAT).
On GitLab, generate a new GitLab PAT with the scopes that Git Gateway needs to act on behalf of your users. For example, to use Git Gateway for Decap CMS users, your access token needs these scopes:
api,read_api,read_repository, andwrite_repository. Learn more in GitLab’s PAT docs.On Netlify, add your GitLab PAT to your Git Gateway settings at
.
# Endpoints
Once the Git Gateway is active, you can talk to your Git provider’s API from your site using /.netlify/git/<git-provider-name>. Requests will be scoped to the selected repository, so for a request like:
GET /.netlify/git/github/contents/
GET /.netlify/git/gitlab/repository/tree
The Gateway will proxy an authenticated version of your request to the matching endpoint in the Git provider’s API:
GET https://api.github.com/repos/your-user/your-repository/contents/
GET https://gitlab.com/api/v4/projects/your-user%2Fyour-repository/repository/tree
GitLab path formatting
GitLab’s namespaced path encoding rule requires a url-encoded %2F between the user and repository names.
The Gateway limits access to the following sub endpoints of the repository:
/repos/:owner/:name/git/
/repos/:owner/:name/contents/
/repos/:owner/:name/pulls/
/repos/:owner/:name/branches/
/repos/:owner/:name/files/
/repos/:owner/:name/commits/
/repos/:owner/:name/tree/
Contact us if you have a use case that requires broader access.
Did you find this doc useful?
Your feedback helps us improve our docs.