Set up Git Sync on Grafana Labs

Setup prerequisites

Fri, 03 Apr 2026 20:44:05 +0000

Before you begin

Caution
Git Sync is available in public preview for Grafana Cloud, and is an experimental feature in Grafana v12 for open source and Enterprise editions. Documentation and support is available based on the different tiers but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.

Git Sync is under development. Refer to Usage and performance limitations for more information. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

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

In Grafana Cloud, Git Sync is being rolled out gradually. For more details refer to Rolling release channels for Grafana Cloud.

To activate Git Sync in Grafana OSS/Enterprise, set the provisioning feature toggle to true:

Open your Grafana configuration file, either grafana.ini or custom.ini.
Enable the provisioning toggle:
ini
```
[feature_toggles]
provisioning = true
```
Save the changes to the file and restart Grafana.

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.

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:
- 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!

Set up Git Sync as code

Fri, 03 Apr 2026 20:44:05 +0000

Set up Git Sync as code

Caution
Git Sync is available in public preview for Grafana Cloud, and is an experimental feature in Grafana v12 for open source and Enterprise editions. Documentation and support is available based on the different tiers but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.

Git Sync is under development. Refer to Usage and performance limitations for more information. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

You can also configure Git Sync using grafanactl, 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 grafanactl. 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 grafanactl, follow these steps:

Understand requirements, known issues, and limitations before you begin
Create the repository CRD
Push the repository CRD to Grafana
Manage repository resources
Verify setup

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>'
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" }

# 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
<GIT_PAT>: Git provider Personal Access Token

Note
Only target: folder is currently supported for Git Sync.

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`)
`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)
`spec.sync.enabled`	Enable synchronization (true/false)
`spec.sync.intervalSeconds`	Sync interval in seconds
`spec.sync.target`	Where to place synced dashboards (`folder`)
`spec.workflows`	Enabled workflows: `write` (direct commits), `branch` (PRs)
`secure.token.create`	GitHub Personal Access Token

Push the repository CRD to Grafana

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

Push the repository configuration:

grafanactl resources push --path <DIRECTORY>

The --path parameter has to point to the directory containing your repository.yaml file.

After pushing, Grafana will:

Create the repository resource
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:

grafanactl resources get repositories

Get repository details

To get details for a specific repository:

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

Update the repository

To update a repository:

grafanactl resources edit repository/<REPOSITORY_NAME>

Delete the repository

To delete a repository:

grafanactl resources delete repository/<REPOSITORY_NAME>

Verify setup

Check that Git Sync is working:

# List repositories
grafanactl resources get repositories

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

Set up Git Sync with Terraform

Fri, 03 Apr 2026 20:44:05 +0000

Set up Git Sync with Terraform

Caution
Git Sync is available in public preview for Grafana Cloud, and is an experimental feature in Grafana v12 for open source and Enterprise editions. Documentation and support is available based on the different tiers but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.

Git Sync is under development. Refer to Usage and performance limitations for more information. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

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 set up the Grafana provider to provide the authentication required to configure Git Sync.

Create a service account and token in Grafana. For more information refer to Service account tokens or Creating and managing 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" {
     cloud_api_url = "<STACK_URL>"
     stack_id = "<STACK_ID>"
     cloud_access_policy_token = "<SERVICE_ACCOUNT_TOKEN>"
   }

Replace the following field values:

STACK_URL with the URL of your Grafana stack, for example https://my-stack.grafana.net/
<STACK_ID> with the Grafana stack ID, if you are using a Grafana Cloud stack
SERVICE_ACCOUNT_TOKEN with the service account token that you created

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

Fri, 03 Apr 2026 20:44:05 +0000

Set up instantaneous pulling and dashboard previews in Pull Requests

Caution
Git Sync is available in public preview for Grafana Cloud, and is an experimental feature in Grafana v12 for open source and Enterprise editions. Documentation and support is available based on the different tiers but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.

Git Sync is under development. Refer to Usage and performance limitations for more information. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

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, a tool such as 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:

[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.

Expose necessary paths only

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

The necessary paths required to be exposed are, in RegExp:

/apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$

Set up image rendering for dashboard previews

Caution
Only available in Grafana OSS and Grafana Enterprise.

Set up image rendering to add visual previews of dashboard updates directly in pull requests. Image rendering also requires webhooks.

To enable this capability, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the Image Renderer service.

Next steps

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