Netlify Git Gateway lets you connect a headless CMS to a private Git repository without exposing your credentials.
Imagine you’re building a website with a headless CMS, like Contentful or Sanity. You want to store your content in a Git repository, but it’s private – you don’t want just anyone to have access. Netlify Git Gateway acts as a secure intermediary, allowing your CMS to push content updates to your private repo without you needing to embed your Git provider’s API keys directly into your CMS or application. This keeps your repository secure while still enabling your content team to manage content seamlessly.
Here’s how it works in practice. Let’s say you’re using Netlify CMS.
First, you need to configure Git Gateway in your config.yml file. This file is the heart of your Netlify CMS setup.
backend:
name: git-gateway
branch: main # Or your default branch
commit_messages:
create: "Create content item: {{title}}"
update: "Update content item: {{title}}"
delete: "Delete content item: {{title}}"
# ... rest of your config.yml
The backend section tells Netlify CMS where to store your content. name: git-gateway is the key here. branch specifies which branch the CMS should interact with. The commit_messages are helpful for tracking changes in your Git history.
Next, you need to set up authentication. Netlify Git Gateway supports several Git providers, including GitHub, GitLab, and Bitbucket. You’ll need to register a new OAuth application with your chosen provider.
For GitHub, go to your GitHub profile settings -> Developer settings -> OAuth Apps -> New OAuth App.
- Application name: Something descriptive, e.g., "MyWebsite CMS Gateway."
- Homepage URL: The URL of your website, e.g.,
https://mywebsite.com. - Authorization callback URL: This is crucial. It should be
https://api.netlify.com/auth/callback.
Once you’ve registered the app, you’ll get a Client ID and a Client Secret. You’ll then need to add these to your Netlify site’s environment variables. In your Netlify dashboard, go to Site settings -> Build & deploy -> Environment. Add two variables:
VCS_AUTH_PROVIDER: Set this togithub(orgitlab,bitbucket).VCS_AUTH_CLIENT_ID: Your GitHub OAuth App’s Client ID.VCS_AUTH_CLIENT_SECRET: Your GitHub OAuth App’s Client Secret.
With these settings in place, when a user logs into Netlify CMS, they’ll be redirected to your Git provider to authorize the connection. Once authorized, Netlify Git Gateway will handle the authentication and allow the CMS to make commits to your private repository on your behalf.
The magic behind this is that Netlify Git Gateway acts as a proxy. Your CMS doesn’t directly talk to your Git provider’s API with your personal credentials. Instead, it talks to Netlify’s Git Gateway API. Netlify then uses the OAuth credentials you’ve configured to authenticate with your Git provider and perform the requested actions (like creating a commit). This means your Git provider credentials never leave Netlify’s secure servers.
A common point of confusion is understanding who is making the commits. When content is updated via the CMS, the commits will appear to be made by the Netlify Git Gateway service itself, or by the specific user who authenticated through the gateway, depending on the Git provider and configuration. This is a deliberate security feature; it prevents accidental or malicious commits from being directly tied to individual developer accounts.
The system handles authentication by issuing short-lived tokens to the CMS. When the CMS needs to perform an action on your repository, it uses one of these tokens to communicate with the Netlify Git Gateway API. The Gateway, in turn, uses the stored OAuth credentials to interact with your Git provider. This token-based approach adds another layer of security and allows for fine-grained control over access.
The most surprising true thing about Netlify Git Gateway is that it doesn’t actually store any Git credentials itself. It’s a stateless service that relies on Netlify’s core infrastructure to manage the secure exchange of OAuth tokens with your Git provider. This means that even if the Git Gateway service were compromised (which is highly unlikely given Netlify’s security practices), no direct Git credentials would be exposed.
When you’re setting up Netlify Git Gateway for the first time, you might encounter issues with the Authorization callback URL. Ensure it’s precisely https://api.netlify.com/auth/callback and not a subdomain or a local development URL.
The next concept you’ll likely explore is implementing fine-grained user permissions for your CMS users, controlling who can edit specific content types.