Before you begin

Before you begin to set up Git Sync, ensure you have the following:

• A Grafana instance (Cloud, OSS, or Enterprise)
• Administration rights in your Grafana organization
• A Git provider
• If you're using webhooks or image rendering, a public instance with external access
  • Optional: The Image Renderer service to save image previews with your PRs

Enable required feature toggles

The provisioning feature toggle is enabled by default in Grafana Cloud and, starting in Grafana v13, for OSS and Enterprise as well. No manual configuration is required.

For more information about feature toggles, refer to Configure feature toggles.

Enable Git providers

If you're using Grafana Enterprise v12.4.0 and want to set up Git Sync with pure Git, GitLab or Bitbucket, or if you're using Grafana OSS v12.4.0 and want to set up Git Sync with pure Git, add them to your configuration file:

1. Open your Grafana configuration file, either grafana.ini or custom.ini.

2. Add the available providers:

   iniCopy

   [provisioning]
   repository_types = "git|github|bitbucket|gitlab|local"
   

3. Save the changes to the file and restart Grafana.

Network connectivity and IP allowlisting

Git Sync requires network connectivity between your Grafana instance and Git server. Understanding the traffic patterns helps you configure firewall rules and allowlists correctly.

Traffic types

Git Sync uses two types of network traffic:

• Sync operations (pull and push): Grafana → Git Server
  • Egress traffic from Hosted Grafana IPs
  • Customer Git servers must allow inbound traffic from these IPs
  • For a list of IPs to add to your Git server's allowlist, refer to Hosted Grafana source IPs
• Webhooks (instantaneous sync): Git Server → Grafana stack
  • Inbound traffic to the stack's public endpoint
  • The Git server must be able to reach *.grafana.net
  • Required only if you're using webhooks

AWS PrivateLink and Private Data Source Connect

Git Sync does not route over AWS PrivateLink or Private Data Source Connect (PDC).

AWS PrivateLink and PDC provide a separate tunnel for data source query traffic (Grafana → your private databases or data sources). Git Sync uses the normal public path from the Hosted Grafana IPs and is independent of PrivateLink/PDC.

If you use AWS PrivateLink or PDC for data sources, you can still use Git Sync. The two features neither interfere with nor depend on each other.

Finally, get acquainted with the following topics:

• Git Sync supported resources
• Git Sync usage and performance limitations
• Role and resource permissions
• For further details on how Git Sync operates, refer to the key concepts

Allow internal or private Git servers

{{< admonition type="note" >}} This setting is available for Grafana v13.0.4 and Grafana v13.1.1 and later. It only applies to self-managed Grafana (OSS and Enterprise), but it's not configurable in Grafana Cloud. {{< /admonition >}}

While public Git servers such as github.com, gitlab.com, and bitbucket.org resolve to public addresses and are always allowed, by default Git Sync rejects repository URLs with a host that resolves to a loopback, a private (RFC 1918), link-local, or an unspecified address. This protects your Grafana instance against server-side request forgery (SSRF).

If you connect Git Sync to a Git server on a private network such as a self-hosted GitHub Enterprise, GitLab, or Bitbucket instance reachable only through an internal address, add its host to the allowed_git_urls allowlist:

1. Open your Grafana configuration file, either grafana.ini or custom.ini.

2. Add each internal Git host to allowed_git_urls as a comma-separated list:

   iniCopy

   [provisioning]
   allowed_git_urls = git.internal.example.com, ghe.example.com:8443
   

3. Save the changes to the file and restart Grafana.

Each entry can be a hostname, host:port, a full URL (only the host is used), a literal IP address, or a CIDR range. If possible, use specific hosts or narrow ranges, since a broad CIDR such as 10.0.0.0/8 re-exposes the entire private range that SSRF protection blocks.

Only add hosts you trust because an allowlisted host receives the configured Git token on every sync, fetch, and push.

Resource and role permissions

By default, folders provisioned with Git Sync have these roles:

• Admin = Admin
• Editor = Editor
• Viewer = Viewer.

Refer to Git Sync permissions for details on how to set up permissions in Git Sync. To modify them, refer to Manage folder permissions.

Refer to Roles and permissions for more information about Grafana roles.

Create a GitHub App

GitHub Apps are tools that extend GitHub functionality. They use fine-grained permissions and short-lived tokens, giving you more control over which repositories are being accessed. Find out more in the GitHub Apps official documentation.

If you chose to authenticate with a newly created GitHub App, you'll need the following parameters:

• GitHub App ID
• GitHub App Private Key
• GitHub App Installation ID

There are many ways to create a GitHub App. The following instructions are informative only, always refer to official GitHub documentation for more details.

To create the GitHub App, follow these steps:

1. Go to https://github.com/settings/apps and click on New Github App, or navigate directly to https://github.com/settings/apps/new
2. Fill in the following fields:
   • Name: Must be unique
   • Homepage URL: For example, your Grafana Cloud instance URL
3. Scroll down to the Webhook section and uncheck the Active box
4. In the Permissions section, go to Repository permissions and set these parameters:
   • Administration: Read-only permission (enables validation of branch protection rules against the configured branch when users can push directly to it; may be used in the future to check other repository settings and make the setup process smoother)
   • Contents: Read and write permission
   • Metadata: Read-only permission
   • Pull requests: Read and write permission
   • Webhooks: Read and write permission
5. Finally, under Where can this GitHub App be installed?, select Only on this account
6. Click on Create Github App to complete the process.

On the app page:

1. Copy the AppID from the About section
2. Select the Generate private key from the banner or scroll down to to the Private Keys section to generate a key
3. A PEM file containing your private key will be downloaded to your computer

Finally, install the app:

1. At the top left of the App page, click on Install App
2. Choose for which user you need to install it, you’ll be redirected to the repository selection screen
3. Choose for which repositories you want to install the app
4. Click Install.
5. On the installation page, copy installationID from the page URL https://github.com/settings/installations/installationID

You can now proceed to Set up Git Sync!