Set up Git Sync on Grafana Labs

Setup prerequisites

Tue, 18 Aug 2026 10:15:08 +0000

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:

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

Add the available providers:

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

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): From Grafana to the Git Server
- Egress traffic from Hosted Grafana IP addresses
- Your Git servers must allow inbound traffic from these IP addresses
- For a list of IP addresses to add to your Git server’s allowlist, refer to Hosted Grafana source IPs
Webhooks (instantaneous sync): From the Git Server to Grafana stack
- Inbound traffic to the stack’s public endpoint
- Your 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 doesn’t route over AWS PrivateLink or Private Data Source Connect (PDC). Instead, Git Sync uses the normal public path from the Hosted Grafana IPs, which is independent from PrivateLink and PDC. AWS PrivateLink and PDC provide a separate tunnel for data source query traffic, from Grafana to your private databases or data sources.

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.

Allow internal or private Git servers

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.

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:

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

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

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

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:

Go to https://github.com/settings/apps and click on New Github App, or navigate directly to https://github.com/settings/apps/new
Fill in the following fields:
- Name: Must be unique
- Homepage URL: For example, your Grafana Cloud instance URL
Scroll down to the Webhook section and uncheck the Active box
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
Finally, under Where can this GitHub App be installed?, select Only on this account
Click on Create Github App to complete the process.

On the app page:

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

Finally, install the app:

At the top left of the App page, click on Install App
Choose for which user you need to install it, you’ll be redirected to the repository selection screen
Choose for which repositories you want to install the app
Click Install.
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!

Next steps

For further details on how Git Sync operates, refer to:

Set up Git Sync as code

Tue, 18 Aug 2026 10:15:08 +0000

Set up Git Sync as code

You can also configure Git Sync using gcx, the Grafana CLI. Since Git Sync configuration is managed as code using Custom Resource Definitions (CRDs), you can create your required resources in YAML files and push them to Grafana using gcx. This approach enables automated, GitOps-style workflows for managing Git Sync configuration instead of using the Grafana UI.

For more information, refer to the following documents:

Repository resource and Connection resource overview
Dashboard CRD Format
Grafana CLI documentation

Set up Git Sync as code with the Grafana CLI

To set up Git Sync as code with gcx, follow these steps:

Create the resources CRDs

If you’re connecting with any of the supported Git providers using a Personal Access Token, you need to create a repository resource to define the connection between your repositories and your Grafana instance.

If you’re connecting to Git Sync with GitHub App, in addition to the repository resource you need to create a connection resource as well.

Create the connection resource

If you’re connecting Git Sync with GitHub App, create a connection.yaml file defining your Git Sync connection configuration:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Connection
metadata:
  name: '<GITHUB_CONNECTION_NAME>'
  namespace: default
spec:
  title: '<REPOSITORY_TITLE>'
  type: github
  url: https://github.com
  github:
    appID: '<GITHUB_APP_ID>'
    installationID: '<GITHUB_INSTALL_ID>'
    serverUrl: '<GITHUB_ENTERPRISE_SERVER_URL>' # Only required for GitHub Enterprise
secure:
  privateKey:
    create: '<GITHUB_PRIVATE_KEY>'

Replace the placeholders with your values:

<GITHUB_CONNECTION_NAME>: The name of your GitHub connection
<REPOSITORY_TITLE>: Human-readable name displayed in Grafana UI
<GITHUB_APP_ID>: GitHub App unique identifier
<GITHUB_INSTALL_ID>: GitHub App installation id
<GITHUB_PRIVATE_KEY>: GitHub Private Key

Create the repository resource

Next, create a repository.yaml file defining your Git Sync configuration. Depending on your Git provider and authentication method, add your Personal Access Token information or the connection name.

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: '<REPOSITORY_NAME>'
spec:
  sync:
    enabled: true
    intervalSeconds: 60
    target: folder
  workflows:
    - write
    - branch
  title: '<REPOSITORY_TITLE>'

# Git Sync for GitHub:
spec:
  type: github
  github:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: grafana/
  # GitHub App connection only:
  connection:
    name: '<GITHUB_CONNECTION_NAME>'
# GitHub Personal Access Token only:
secure:
  token: { create: 'GIT_PAT' }

# Git Sync for GitHub Enterprise:
spec:
  type: githubEnterprise
  githubEnterprise:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: grafana/
  # GitHub Enterprise App connection only:
  connection:
    name: '<GITHUB_ENTERPRISE_CONNECTION_NAME>'
# GitHub Personal Access Token only:
secure:
  token: { create: 'GIT_PAT' }

# GitLab Personal Access Token only:
spec:
  type: gitlab
  gitlab:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
secure:
  token: { create: 'GIT_PAT' }

# Bitbucket Personal Access Token only:
spec:
  type: bitbucket
  bitbucket:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    tokenUser: tokenuser
secure:
  token: { create: 'GIT_PAT' }

# Pure Git only:
spec:
  type: git
  git:
    url: '<GIT_REPO_URL>'
    branch: '<BRANCH>'
    path: 'grafana/'
    tokenUser: tokenuser
secure:
  token: { create: 'GIT_PAT' }

Replace the placeholders with your values:

<REPOSITORY_NAME>: Unique identifier for this repository resource
<REPOSITORY_TITLE>: Human-readable name displayed in Grafana UI
<GIT_REPO_URL>: GitHub repository URL
<BRANCH>: Branch to sync
<GITHUB_CONNECTION_NAME>: The name of your GitHub connection
<GITHUB_ENTERPRISE_CONNECTION_NAME>: The name of your GitHub Enterprise connection
<GIT_PAT>: Git provider Personal Access Token

Note
Git Sync supports two sync targets: target: folder (the default) creates a folder named after the repository and places synced resources inside it, while target: folderless places synced resources at the top level without creating a wrapper folder. Refer to Sync targets for details.

Configuration parameters

The following configuration parameters are available:

Field	Description
`metadata.name`	Unique identifier for this repository resource
`spec.title`	Human-readable name displayed in Grafana UI
`spec.type`	Repository type (`github`, `githubEnterprise`)
`spec.github.url`	GitHub repository URL
`spec.github.branch`	Branch to sync
`spec.github.path`	Directory path containing dashboards
`spec.github.generateDashboardPreviews`	Generate preview images (true/false) (Only available in GitHub)
`spec.sync.enabled`	Enable synchronization (true/false)
`spec.sync.intervalSeconds`	Sync interval in seconds
`spec.sync.target`	Where to place synced dashboards (`folder` or `folderless`)
`spec.workflows`	Enabled workflows: `write` (direct commits), `branch` (PRs)
`secure.token.create`	GitHub Personal Access Token

Push the resources to Grafana

Before pushing any resources, configure gcx with your Grafana instance details. Refer to the Grafana CLI documentation for setup instructions.

Push the repository configuration. If you’re using GitHub App to connect Git Sync, push the connection resource configuration file as well.

gcx resources push --path <DIRECTORY>

The --path parameter has to point to the directory containing your repository.yaml and connection.yaml files.

After pushing, Grafana will:

Create the required resources (repository and, for GitHub App, connection)
Connect to your GitHub repository
Pull dashboards from the specified path
Begin syncing at the configured interval

Manage repository resources

List repositories

To list all repositories:

gcx resources get repositories

Get repository details

To get details for a specific repository:

gcx resources get repository/<REPOSITORY_NAME>
gcx resources get repository/<REPOSITORY_NAME> -o json
gcx resources get repository/<REPOSITORY_NAME> -o yaml

Update the repository

To update a repository:

gcx resources edit repository/<REPOSITORY_NAME>

Delete the repository

To delete a repository:

gcx resources delete repository/<REPOSITORY_NAME>

Verify setup

Check that Git Sync is working:

# List repositories
gcx resources get repositories

# Check Grafana UI
# Navigate to: Administration → Provisioning → Git Sync

Set up Git Sync with Terraform

Tue, 18 Aug 2026 10:15:08 +0000

Set up Git Sync with Terraform

You can also configure Git Sync via the Grafana provisioning app platform using Terraform.

Before you begin

Before you begin, make sure to have the following:

A Grafana Cloud account or an on-prem Grafana instance.
Administrator permissions in your Grafana stack/instance.
Terraform 1.11 or later installed on your machine. Refer to the Terraform install documentation to learn more.

Note
Save all of the following Terraform configuration files in the same directory.

Configure the Grafana provider

Use this Terraform configuration to configure the Grafana provider with the authentication required to set up Git Sync.

Create a service account and token in Grafana. For more information refer to Service account tokens or Create and manage a Grafana Cloud stack using Terraform.
Make sure that the token has the Admin or the Provisioning:Repositories writer permission.

Create a file named main.tf and add the following:

   terraform {
     required_providers {
       grafana = {
         source  = "grafana/grafana"
         version = ">= 4.28.1"
       }
     }
   }

   provider "grafana" {
     url = "https://<your-stack>.grafana.net/"
     auth = var.grafana_service_account_token
     stack_id = var.grafana_stack_id
   }

Replace the following field values:

<Stack-URL> with the URL of your Grafana stack (for example, https://my-stack.grafana.net/)
<Service-account-token> with the service account token that you created (or <USERNAME>:<PASSWORD> for basic auth)
<Stack-ID> with the Grafana stack ID, if you are using a Grafana Cloud stack

Caution
The Git Sync Terraform resources are App Platform resources and talk directly to the Grafana stack’s API.

Do not use Grafana Cloud provider settings in this configuration. Configure the provider with url and auth (not cloud_api_url and cloud_access_policy_token). If you’re using Grafana Cloud, set stack_id to your stack ID.

Create the resources to use Git Sync

You need two resources for configure and manage Git Sync:

The repository resource configures the Git repository to sync Grafana resources with. For examples, refer to Repository resource in the Terraform registry.
The connection resource configures your Git provider credentials. For examples, refer to Connection resource in the Terraform registry.

For better understanding of the required resources, refer to Git Sync key concepts.

Instantaneous pulling and dashboard previews

Tue, 18 Aug 2026 10:15:08 +0000

Set up instantaneous pulling and dashboard previews in Pull Requests

After setup, you can optionally extend Git Sync by enabling pull request notifications and image previews of dashboard changes.

Capability	Benefit	Requires
A table summarizing changes to your pull request	A convenient way to save changes back to GitHub	Webhooks configured
A dashboard preview image to a PR	A snapshot of dashboard changes to a pull request outside Grafana	Image renderer and webhooks configured

Set up webhooks for real-time notification and pull request integration

Real-time notifications (or automatic pulling) is enabled and configured by default in Grafana Cloud.

In Grafana OSS/Enterprise, Git Sync uses webhooks to enable real-time updates from GitHub public repositories, or to enable pull request integrations. Without webhooks the polling interval is set during configuration, and is 60 seconds by default. You can set up webhooks with whichever service or tooling you prefer: Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as ngrok.

To set up webhooks:

Expose your Grafana instance to the public Internet.
- Use port forwarding and DNS, ngrok, or any other method you prefer.
- The permissions set in your GitHub access token provide the authorization for this communication.
After you have the public URL, add it to your Grafana configuration file:
ini
```
[server]
root_url = https://<PUBLIC_DOMAIN>
```
Replace <PUBLIC_DOMAIN> with your public domain.

To check the configured webhooks, go to Administration > General > Provisioning and click the View link for your GitHub repository.

Webhook limits

Git Sync registers its own webhooks for each repository connection, so when several Grafana instances sync the same repository, each connection adds to this total. Since Git providers limit the amount of webhooks you can set for each repository, when the limit is exceeded, your Git provider rejects new webhooks.

For example, in GitHub you can get an error such as:

GitHub API error (HTTP 422: Validation Failed: The "pull_request" event cannot have more than 20 hooks; The "push" event cannot have more than 20 hooks)

If you hit this limit, you can either:

Remove unused or duplicate webhooks from your repository’s Settings > Webhooks page.
Disable webhook integration for connections that don’t need real-time sync so those instances poll on an interval instead. Refer to Webhook options to disable webhook integration.

Webhook limitations per provider

The following limits apply:

GitHub limits each repository to 20 webhooks per event type, such push and pull_request. For more information refer to the official GitHub webhooks documentation.
GitLab defaults to 100 webhooks for each project, 50 for each group, although subgroup webhooks are not counted towards parent group limits. Refer to GitLab settings for more information.
BitBucket limits to 50 webhooks per repository. Refer to BitBucket webhook documentation for more details.

Set a publicly-reachable URL

If you need to point [server] root_url to an internal address (for example, when Grafana runs behind a private ingress in a Kubernetes cluster), set the publicly-reachable URL with [provisioning] public_root_url instead. This URL is used both to register webhook callbacks with the Git provider and as the base for screenshot images embedded in pull-request comments, which the Git provider’s servers fetch from the public internet.

[server]
root_url = http://internal.cluster.local

[provisioning]
public_root_url = https://<PUBLIC_DOMAIN>

The per-repository spec.webhook.baseUrl field still overrides public_root_url for webhook registration, and screenshot URLs always use public_root_url (or root_url when unset).

Expose necessary paths only

If your security setup doesn’t permit publicly exposing the Grafana instance, you can either choose to allowlist the Git provider’s IP addresses, or expose only the necessary paths.

For information about the traffic between Grafana and your Git server, refer to Network connectivity and IP allowlisting.

In RegExp, the necessary paths required to be exposed are /apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$.

Set up image rendering for dashboard previews

Caution
Available in Grafana OSS and Grafana Enterprise only.

To set up image rendering to add visual previews of dashboard updates directly in pull requests, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the Image Renderer service.

Image rendering requires webhooks.

Next steps

To learn more about using Git Sync refer to the following documents: