Before you begin

{{< admonition type="caution" >}}

Git Sync is now GA for Grafana Cloud, OSS and Enterprise. Refer to Usage and performance limitations to understand usage limits for the different tiers.

Contact Grafana for support or to report any issues you encounter and help us improve this feature.

{{< /admonition >}}

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

Moreover, make sure you're not blocking any of the Grafana services IPs. For a list of IPs you need to add to your allowlist, refer to Hosted Grafana source IPs.

Finally, get acquainted with the following topics:

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

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.

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!

Folder roles and permissions

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

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

To modify them, refer to Manage folder permissions.

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