Introduction to Git Sync on Grafana Labs

Git Sync Key concepts

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

Git Sync key concepts

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

Key Git Sync components

Before you start using Git Sync, understand how the key Git Sync components relate:

Grafana instance

A Grafana instance is a running Grafana server. Multiple instances can:

Connect to the same Git repository using different Repository configurations.
Sync from different branches of the same repository.
Sync from different paths within the same repository.
Sync from different repositories.

Git repository

A Git repository is the external storage you want to sync your Grafana instance with. You can organize your Git repository in several ways:

Single branch, multiple paths: Use different directories for different purposes. For example, dev/, prod/, or team-a/.
Multiple branches: Use different branches for different environments or teams. For example, main, develop, or team-a.
Multiple repositories: Use separate repositories for different teams or environments.

Flexible configuration for your Git Sync repositories

Git Sync repositories support different combinations of repository URL, branch, and path:

Different Git repositories: Each environment or team can use its own repository.
- Instance A: repository: your-org/grafana-prod.
- Instance B: repository: your-org/grafana-dev.
Different branches: Use separate branches within the same repository.
- Instance A: repository: your-org/grafana-manifests, branch: main.
- Instance B: repository: your-org/grafana-manifests, branch: develop.
Different paths: Use different directory paths within the same repository.
- Instance A: repository: your-org/grafana-manifests, branch: main, path: production/.
- Instance B: repository: your-org/grafana-manifests, branch: main, path: development/.
Any combination: Mix and match based on your workflow requirements.

Git Sync repository resource

A repository resource is a Grafana configuration object that defines the connection between a group of repositories and your Grafana instance via Git Sync.

Which Git repository to sync with your Grafana instance.
Which branch to use.
Which directory path to synchronize.
Sync behavior and workflows.

Each repository resource creates bidirectional synchronization between a Grafana instance and a specific location in Git.

Git Sync connection resource

A connection is the authentication setup between Grafana and an external Git provider, required when you’re not using a Personal Access Token or a static token to authenticate. Use it to authorize access to your external repositories, and to generate or refresh the credentials for Git Sync. A single connection can be reused across multiple repositories.

For example, if you’re using GitHub App to authenticate, the connection represents the app installation. Grafana uses this connection to authenticate with GitHub, create access tokens, and authorize repository access on your behalf.

The connection resource includes:

The external provider configuration: The authentication mechanism Grafana uses to communicate with the Git provider (for example, a GitHub App).
The provider authorization or installation: The authorized entity that allows Grafana to request tokens from the provider.
Repository access scope: The set of repositories that the connection (and therefore, Grafana) is authorized to access in the Git provider.

How does Git Sync behave?

Git Sync is bidirectional, and syncs a repository resource with your Grafana instance. You can modify provisioned resources both from the Grafana UI or from the synced GitHub repository, and changes will be reflected in both places:

Grafana monitors the specified Git location (repository, branch, and path).
Grafana creates a folder in Dashboards (typically named after the repository).
Grafana creates dashboards from dashboard JSON files in Git within this folder.
Grafana commits dashboard changes made in the UI back to Git.
Grafana pulls dashboard changes made in Git and updates dashboards in the UI.
Synchronization occurs at regular intervals (configurable), or instantly if you use webhooks.

You can find the provisioned dashboards organized in folders under Dashboards.

Sync targets

With Git Sync you can place synced resources in Grafana in two ways:

Folder sync: Grafana creates a folder named after the repository and places all synced resources inside it. Subdirectories in the repository become subfolders within that folder. This is the default behavior.
Folderless sync: Grafana places synced resources at the top level, without creating a wrapper folder. Files at the repository path root become top-level resources, and subdirectories become top-level folders.

Use folder sync to keep each repository’s resources grouped together under a dedicated folder. Use folderless sync when you want provisioned resources to appear at the top of your Dashboards view instead of nested inside a repository folder.

Both modes can coexist with each other and with resources that aren’t managed by Git Sync.

The following examples use the same repository to show how the same files appear with each mode.

The repository grafana-manifests syncs from the path grafana/:

your-org/grafana-manifests/
└── grafana/
    ├── cpu-metrics.json
    └── team-platform/
        ├── _folder.json
        └── memory-usage.json

The _folder.json file stores the team-platform folder’s stable UID and display name, so the folder keeps its identity and permissions if you move or rename it in the repository. Refer to The Git Sync folder metadata file for details.

The instance also has content that isn’t managed by Git Sync: a manually created Ops folder and an Ad-hoc dashboard.

With folder sync, a repository folder wraps the synced resources, alongside the unprovisioned content:

Dashboards
├── 📁 grafana-manifests/      ← managed by Git Sync
│   ├── CPU Metrics Dashboard
│   └── 📁 team-platform/
│       └── Memory Usage Dashboard
├── 📁 Ops/                    ← not managed by Git Sync
│   └── Ops dashboard
└── Ad-hoc dashboard           ← not managed by Git Sync

With folderless sync, the same files map to the top level, next to the unprovisioned content:

Dashboards
├── CPU Metrics Dashboard      ← managed by Git Sync
├── 📁 team-platform/          ← managed by Git Sync
│   └── Memory Usage Dashboard
├── 📁 Ops/                    ← not managed by Git Sync
│   └── Ops dashboard
└── Ad-hoc dashboard           ← not managed by Git Sync

Folderless sync only manages the resources it provisions. The unprovisioned Ops folder and Ad-hoc dashboard are left untouched.

Multiple folderless repositories

Because folderless sync doesn’t create a wrapper folder, several folderless repositories can sync to the top level at the same time. Each repository manages only the resources it provisions:

Dashboards
├── CPU Metrics Dashboard      ← managed by grafana-manifests
├── 📁 team-platform/          ← managed by grafana-manifests
│   └── Memory Usage Dashboard
├── Billing Overview           ← managed by finance-dashboards
├── 📁 invoices/               ← managed by finance-dashboards
│   └── Monthly Invoices
└── Ad-hoc dashboard           ← not managed by Git Sync

Git Sync states

Your Grafana instance can be in one of the following Git Sync states:

Unprovisioned: None of the instance’s resources are being managed by Git Sync.
Partially provisioned: Some of the resources are controlled by Git Sync.
Fully provisioned: All supported resource types are managed by Git Sync. Unsupported resources are not managed.

Example: Relationship between repository, branch, and path

Here’s an example showing how the repository, branch, and path concepts work together:

Configuration:

Repository: your-org/grafana-manifests
Branch: main
Path: team-platform/grafana/

In Git (on branch main):

your-org/grafana-manifests/
├── .git/
├── README.md
├── team-platform/
│   └── grafana/
│       ├── cpu-metrics.json       ← Synced
│       ├── memory-usage.json      ← Synced
│       └── disk-io.json           ← Synced
├── team-data/
│   └── grafana/
│       └── pipeline-stats.json    ← Not synced (different path)
└── other-files.txt                ← Not synced (outside path)

In the Grafana Dashboards view:

Dashboards
└── 📁 grafana-manifests/
    ├── CPU Metrics Dashboard
    ├── Memory Usage Dashboard
    └── Disk I/O Dashboard

Key takeaways:

Grafana only synchronizes files within the specified path (team-platform/grafana/).
Grafana ignores files in other paths or at the repository root.
The folder name in Grafana comes from the repository name.
Dashboard titles come from the JSON file content, not the filename.

Usage and performance limitations

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

Usage and performance limitations

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

Performance considerations

When Git Sync is enabled, the database load might increase, especially if your Grafana instance has many folders and nested folders. Evaluate the performance impact, if any, in a non-production environment.

Usage tiers and limits

The following Git Sync per-tier limits apply:

Tier	Cloud - Free	Cloud - Other	On-prem OSS	On-prem Enterprise
Amount of repositories	1	10	10 (default)	10 (default)
Amount of synced resources per repository	20	1,000	No limit	No limit

Note
On Grafana Cloud, tier limits can’t be changed from configuration. Contact Support if you need a higher connection limit, or shard by capacity instead of using a single connection per team or microservice.

On self-managed Grafana (OSS or Enterprise), the repository count of 10 in the table is the default, not a hard ceiling. Raise or remove it with [provisioning] max_repositories in the Grafana configuration file. On-prem resources per repository stay unlimited by default (max_resources_per_repository = 0), and you can set a cap if you want one.

Refer to Modify your usage limits for more details.

Recommended limits

On Grafana Cloud, the repository-connection limit is a per-stack limit. On self-managed Grafana, the effective limit is whatever you set for max_repositories (default 10).

Do not sync more than 1,000 resources per repository connection as of today. This isn’t an arbitrary cap: beyond roughly 1,000 resources per connection, the sync workflow puts noticeable load on Grafana itself, which may result in slower syncs and increased database load.

Both of these limits are early figures. As Git Sync matures, these limits will raise by orders of magnitude. The goal is for Git Sync to support around 100 repository connections per stack, and up to roughly 1,000 in the longer term, with similar increases to the number of resources you can sync per connection.

If these limits are affecting your use of Git Sync, get in touch and explain your situation. You may also share any ideas or suggestions.

For details on usage and storage limits, refer to Dashboard and folder limits.

Modify your usage limits

Before changing your usage limits, study your specific use case. Design the repository structure carefully, and determine how many repositories and how many resources you can support. For example, setting over 1,000 resources per repository may impact your system’s performance.

In many cases, splitting a single repository across multiple connections, as described in Scale beyond 1,000 resources per repository, is a better option than raising the limits.

Grafana Cloud

On Grafana Cloud, limits are enforced per tier and can’t be edited from configuration. The 10-connection limit can be increased slightly on request, but splitting a single repository across multiple connections is the recommended way to sync more resources without changing tier limits.

Limit increases aren’t granted automatically. When you request one, Support will ask you to describe your use case to understand why the current limits aren’t enough, and assess whether the increase is necessary and safe for your stack’s performance.

Grafana OSS/Enterprise

In Grafana On-prem (OSS or Enterprise), the table value of 10 repositories is only the default, not a hard ceiling. Resources per repository remain unlimited by default. The 1,000-resources-per-connection figure is a performance recommendation, not an on-prem default cap.

If you’re an on-prem user you can change the limits directly through configuration settings, as described below.

To customize the limits use one of these configuration settings:

Use max_repositories to set how many repositories you can sync. Default is 10. Set to 0 for unlimited repositories. Refer to max_repositories in the Configure Grafana section to learn more.
Use max_resources_per_repository to set the amount of resources per repository to sync. Default is 0 (unlimited). Refer to max_resources_per_repository in the Configure Grafana section to learn more.

Scale beyond 1,000 resources per repository

If a single repository holds more than 1,000 resources, you don’t have to raise the per-repository limit. Instead, connect the same repository multiple times, with each connection pointing to a different folder (path) in the repository. Each connection syncs its own subset of resources and counts toward the 1,000-resource recommendation independently.

Because a stack allows up to 10 repository connections, this lets you sync up to roughly 10,000 resources from a single repository while keeping each connection within the recommended range.

When you split a single repository across several connections, use folderless sync for each connection. With folder sync (the default), every connection creates its own wrapper folder named after the repository, so splitting the repository would change your folder hierarchy and nest resources one level deeper. Folderless sync places each connection’s resources at the top level, so the split has no effect on how your dashboards and folders are organized in Grafana.

If you need more than that, the 10-connection limit can be increased slightly for Cloud stacks on request. Contact Support to discuss your use case.

On Grafana Cloud, syncing this many resources may also exceed your stack’s maximum number of dashboards. If it does, you’ll need to increase that limit as well. Refer to Dashboard and folder limits to review and adjust your dashboard limits.

Shard by capacity, not by team

When you have many teams or tenants, it’s tempting to create one connection per team so each team maps to its own connection. Avoid this: it consumes connections quickly, doesn’t scale as teams grow, and on Grafana Cloud a single stack can’t be granted the hundreds of connections this would require.

Instead, shard by capacity. Create one repository and group teams into a small number of shard folders, each holding up to about 1,000 resources, and connect each shard folder separately. For example, a customer with 190 teams and 900 resources fits comfortably in a single shard today:

your-org/grafana-manifests/
├── shard-1/        ← ~900 resources today, connected now
│   ├── team-a/
│   ├── team-b/
│   └── ...
├── shard-2/        ← empty for now, add a connection when shard-1 approaches 1,000
├── shard-3/        ← add later as you keep growing
└── shard-4/        ← ...up to 10 shards / connections per stack

As the number of resources grows, add shard-2, shard-3, and later shards, and connect each one. You can move teams between shards at any time to balance the load, so you only pay for the connections you actually need and can grow up to the 10-connection limit without restructuring your repository.

If sharding isn’t practical for your setup, try raising the per-connection resource limit modestly, for example from 1,000 to a limit in the 1,200 - 1,500 range. This is a small adjustment for a bit of extra headroom, not an order-of-magnitude increase. Still, do not go beyond 1,500 resources per connection because of the performance impact on Grafana. For substantially larger scales, sharding remains the recommended approach.

Git Sync across multiple organizations

Git Sync works across multiple organizations for self-managed Grafana instances. You can set up Git Sync independently in each of your organizations, and what you sync in one organization does not affect another. Teams that share a single Grafana instance across separate organizations can each manage their own provisioning from Git.

This feature is available starting in Grafana 13.0.4, but not supported until Grafana 13.1.1.

Compatible Git providers

Git Sync is available for any Git provider through a Pure Git repository type, and has specific enhanced integrations for GitHub, GitLab and Bitbucket.

Provider	Available in	Authentication
Pure Git	Cloud, OSS, Enterprise	Personal Access Token
GitHub	Cloud, OSS, Enterprise	Personal Access Token or GitHub App
GitHub Enterprise (Server and Cloud)	Cloud, Enterprise	Personal Access Token or GitHub App
GitLab	Cloud, Enterprise	Personal Access Token
Bitbucket	Cloud, Enterprise	API token with scopes

Note that Pure Git, GitLab and Bitbucket are supported in Grafana v12.4.x or later only. Refer to Enable Git providers to set them up.

To learn more about Git, refer to Getting Started - About Version Control of the Pro Git book in the official Git documentation.

The Pure Git repository type

The Pure Git repository type uses the Smart HTTP protocol v2 (Git over HTTPS), with no provider-specific logic. Pure Git delivers the core Git Sync workflow: your repository is the source of truth, you may edit dashboards in the UI, and Grafana stays in sync.

Note
Pure Git only supports Smart HTTP protocol v2. Earlier protocol versions (v1, v0) and SSH transport are not supported.

Make sure your Git server supports protocol v2 over HTTPS. Some providers, like Azure DevOps, only use v1 and are therefore not compatible with Git Sync.

However, Pure Git doesn’t include any features that require provider APIs, such as webhook-driven instant sync, automated PR comments, or deep links to source files.

Enhanced integrations: GitHub, GitHub Enterprise, GitLab, Bitbucket

If your Git provider is GitHub, GitHub Enterprise (Server and Cloud), GitLab, or Bitbucket, use the enhanced integration. Enhanced integrations understand the platform you’re using, allowing workflows that feel native: automated pull request comments with dashboard previews, instant webhook-based sync, or direct navigation from Grafana to source files in your provider’s UI.

The GitHub enhanced integration is the most feature-complete experience today. It’s available in Grafana OSS, Enterprise, and Cloud, and enables richer pull request workflows, deeper linking between Grafana and GitHub, and tighter integration into review processes.

The GitLab and Bitbucket integrations are only available in Grafana Enterprise and Grafana Cloud. While they’re less developed for the moment, expect continued improvements around pull request workflows, linking, and sync behavior.

Resource support and compatibility

Git Sync only supports dashboards and folders. Alerts, data sources, panels and other resources are not supported yet.

If you’re a Grafana Cloud user, you can check the Grafana roadmap portal to learn about future improvements.

Resource compatibility

If you’re using Git Sync in Grafana OSS or Grafana Enterprise, some supported resources might be in an incompatible data format. If this happens, syncing will be blocked. Compatibility issues will be fixed with an upcoming migration tool.

A resource can be:

Is the resource?	Compatible	Incompatible
Supported	The resource can be managed with Git Sync.	The resource is supported but has compatibility issues. It cannot be managed with Git Sync.
Unsupported	The resource is not supported and cannot be managed with Git Sync.	Not applicable.

Nested folders

Git Sync supports up to four nested folders within a repository.

Known limitations

Migration to Git Sync

Full-instance sync is experimental.

When migrating to resources to Git Sync, you can still create, edit or delete resources, but changes may not be exported. The duration of this process depends on the number of resources involved.

Use existing resources

To add existing resources as provisioned Git Sync resources, you can use the Import dashboards tool, save them from the UI, save them as JSON files and commit them to the synced repository, or use gcx. Refer to Export non-provisioned resources from Grafana for more details. When migrating existing dashboards, the folder structure will be replicated in the provisioned repository.

Caution
Git Sync cannot take ownership of a resource while an unmanaged resource with the same UID exists in Grafana, so you may need to manually remove the original resources to ensure the transition to provisioned resources. Since deleting resources implies certain operational caveats, refer to How to delete existing resources in Grafana for more information.

Restore resources

Restoring resources from the UI is currently not possible. As an alternative, you can restore dashboards directly in your GitHub repository by raising a PR, and they will be updated in Grafana.

Set up Git Sync

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

Set up Git Sync

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

To set up Git Sync and synchronize your Grafana dashboards and folders with a GitHub repository, follow these steps:

Read Before you begin carefully.
Set up Git Sync using the UI, with Terraform, or as code.
After setup, check your dashboards have been synced correctly.
Optionally, you can also extend Git Sync with webhooks and image rendering.

Alternatively, on-prem file provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system. Refer to Provision resources on-prem for more details.

Set up Git Sync using the UI

To set up Git Sync from the Grafana UI, follow these steps:

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Select Administration > General > Provisioning in the left-side menu to access the Git Sync configuration screen. If you already have an active Git Sync connection, go to the Get started tab.
Select your provider to start a new Git Sync setup: GitHub, GitLab, Bitbucket, or Pure Git.
Configure the provisioning repository.
Choose what content to sync with Grafana.
Synchronize with external storage.
Choose additional settings.

Select your provider

Git Sync is available for any Git provider through a Pure Git repository type, and has specific enhanced integrations for GitHub, GitHub Enterprise, GitLab and Bitbucket. Refer to Compatible providers for more details.

Select any of these options to proceed:

Configure with GitHub

If you want to configure Git Sync for public cloud GitHub, you can connect using a Personal Access Token or with GitHub App. Whichever you choose, make sure you have the following permissions:

Administration: Read-only permission
- This enables validation of branch protection rules against the configured branch when users can push directly to it
- In the future, it might be used 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

For information on how to set up each method, refer to:

Create a new fine-grained personal access token. You need a Personal Access Token from an Admin role to set up the repository. GitHub only grants the Webhooks: Read and write permission to repository admins, so tokens created by non-admin users can’t manage the webhooks Git Sync relies on for instantaneous updates and pull request previews.
Create a GitHub App.

Connect with a GitHub Personal Access Token

Fill in the following fields:

Paste the Repository URL for your GitHub repository into the text box.
Paste your Personal Acccess Token.

Select Configure repository to set up your provisioning folder.

Connect with GitHub App

If you want to configure Git Sync for GitHub and authenticate with GitHub App:

If you already have an existing GitHub App connected, select Choose an existing app.
1. From the drop-down menu, select the connection you want to use.
2. Paste the Repository URL for your GitHub repository into the text box.
If you want to connect using a new GitHub App, select Connect to a new app.
1. Type in the following fields:
  - The ID of the GitHub App you want to use.
  - The GitHub Installation ID.
  - The Private Key.
2. Paste the Repository URL for your GitHub repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure with GitHub Enterprise

Similarly, you can connect to GitHub Enterprise Server or GitHub Enterprise Cloud using a Personal Access Token or with GitHub App. Refer to Configure with GitHub for details on the required permissions.

Connect with a GitHub Personal Access Token

Fill in the following fields:

Paste the Repository URL for your GitHub repository into the text box.
Paste your Personal Acccess Token.

Select Configure repository to set up your provisioning folder.

Connect with GitHub App

If you want to configure Git Sync for GitHub Enterprise and authenticate with GitHub App:

If you already have an existing GitHub App connected, select Choose an existing app.
1. From the drop-down menu, select the connection you want to use.
2. Paste the Repository URL for your GitHub repository into the text box.
If you want to connect using a new GitHub App, select Connect to a new app.
1. Type in the following fields:
  - The ID of the GitHub App you want to use.
  - The GitHub Installation ID.
  - The Private Key.
  - The URL of your GitHub Enterprise instance.
    - For GitHub Enterprise Cloud, it looks like https://<enterprise-slug>.ghe.com.
    - For GitHub Enterprise Server, your custom URL.
2. Paste the Repository URL for your GitHub repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure with GitLab

If you want to configure Git Sync for GitLab, you need a GitLab Personal Access Token. To create one, sign in to GitLab and create a token with these permissions:

Repository: Read and write permission
User: Read only permission
API: Read and write permission

If you’re using a token from a service account, you need to add the service account to the GitLab project as a member to avoid authentication issues.

After creating the token, return to Grafana and fill in the following fields:

Paste the token into the Project Access Token text box.
Paste the Repository URL for your GitLab repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure with Bitbucket

If you want to configure Git Sync for Bitbucket, you need a Bitbucket API token with scopes. To create one, sign in to Bitbucket and create an API token with these permissions:

Repositories: Read and write permission
Pull requests: Read and write permission
Webhooks: Read, write, and delete permission

Return to Grafana and fill in the following fields:

Paste the token into the API Token text box.
Paste the Repository URL for your Bitbucket repository into the text box.

Use the Git clone URL for the repository, not the URL that appears in your browser’s address bar when you view the repository. To find it, select Clone in Bitbucket and copy the HTTPS URL. The clone URL ends in .git, and its format depends on your Bitbucket deployment:
- Bitbucket Cloud: https://bitbucket.org/<workspace>/<repository>.git
- Bitbucket Data Center and Server: https://<bitbucket-host>/scm/<PROJECT>/<repository>.git
Tip
If Grafana returns an ls-refs error when it connects to the repository, check that you entered the clone URL and not the browser URL.

Select Configure repository to set up your provisioning folder.

Configure with Pure Git

If you’re using another Git provider, you need to use the Pure Git option to configure your connection with a Personal Access Token:

Paste the access token or password of the Git repository you want to sync in Access Token.
Enter a Username. Git Sync will use this name to access the Git repository.
Paste the Repository URL of your Git repository into the text box.

Select Configure repository to set up your provisioning folder.

Configure the provisioning repository

After configuring your connection authentication, continue to enter the details of the repository you want to use for provisioning:

Enter a Branch to use for provisioning. The default value is main.
Optionally, you can add a Path to a subdirectory where your dashboards are stored.

Select Choose what to synchronize to have the connection to your repository verified and continue setup.

Choose what to synchronize

Next, sync the external resources you specified in the previous step with your Grafana instance. You can store these provisioned resources in Grafana, either at the root of the provisioned folder or in a new folder, without affecting the rest of your instance.

To set up synchronization:

Select whether you want to store synced resources in a new folder or at root level in Grafana. For more information on these options, refer to Sync targets. The UI provides information about the available resources you can sync.
Enter a Display name for your repository connection. All the synced resources from this Git Sync connection will appear under the this name in the Grafana UI.
Click Synchronize with external storage to continue.
You can repeat this process for up to 10 connections.

Optionally, you can export any unmanaged resources into the provisioned folder. See how in Synchronize with external storage.

Select Choose additional settings to continue setup.

Synchronize with external storage

To proceed with the sync:

Review the known limitations.
You may see the experimental checkbox Migrate existing resources, which allows you to migrate your unmanaged dashboards to the provisioned folder. If you don’t, refer to Export non-provisioned resources from Grafana to learn how to migrate your existing resources.
Click Begin synchronization to create the Git Sync connection. When the process is completed, you’ll see a summary of the synced resources.

Click Choose additional settings for the final configuration steps.

Choose additional settings

In this last step, you can configure additional options for Git Sync. When you’re done, click Finish to complete the setup.

Sync interval

Use the Sync interval (seconds) setting to indicate how often you want your Grafana instance to automatically pull updates from the folder managed with Git Sync. The default value is 300 seconds in Grafana Cloud, and 60 seconds in Grafana OSS/Enterprise.

Optional settings

You can also select these optional settings:

Check Read only to ensure resources can’t be modified in Grafana.
Check Enable pull request option when saving to choose whether to open a pull request when saving changes. If the repository does not allow direct changes to the main branch, a pull request may still be required.
Check Enable push to configured branch to allow direct commits to the configured branch.
Check Generate dashboards previews to create preview links for pull requests. This option requires using image rendering and activating public access.

After deciding on these options, you can chose to configure Webhooks or a verified account with the Commit options. Alternatively, if you want your your commits to remain unsigned, click Save to continue.

Webhook options

In the Webhook options menu, you can type in an URL to override the auto-detected URL used to register webhooks. Make sure you have the appropriate permissions to set up and manage webhooks.

You can also check the Disable webhook integration. When checked, Grafana doesn’t register or receive webhook events, and polls the repository on an interval instead. Use this when your Grafana instance is not reachable from the public internet.

Git providers limit the amount of webhooks they allow in their repositories. Refer to Webhook limits for more information and to learn how to proceed if you reach these limits.

Signed commit options

Starting in Grafana 13.1.0, you can configure a verified account with a signing key, allowing you to enforce your users to sign commits so your Git provider can mark them as Verified. Git Sync supports GPG, SSH, and S/MIME keys.

Starting in Grafana 13.2.0, by default all commits use the signed-in Grafana user as the commit author. For more details, refer to Authoring options.

For the moment, Git Sync doesn’t support:

Passphrase-protected keys.
Verification of individual accounts.

Follow the UI wizard to fill in the required fields to set up any of these options, and refer to the sections below for more details.

Pre-requirements

In order to implement signed commits, make sure that you set up a specific verification account in your Git provider. You’ll need your account’s signing key, name and email to set up verification.

For more details on how to create your keys for Git authentication, refer to the official documentation:

GitHub: Managing commit signature verification
GitLab: Signed commits
Bitbucket: Controlling access to code

Example: Sign your commits with an SSH key

To enforce signed commits using an SSH key follow these steps:

Open the Commit options (advanced) menu.
Under Commit signing, select SSH.
Fill in the following fields:
- The private key for the account to verify.
- The signer’s name to be displayed in your Git provider.
- The signer’s e-mail address, which must match the one in the signing key.
Click Save.

After completing the key configuration, any commits your users make to the provisioned folder will appear as Verified.

Authoring options

Starting in Grafana 13.2.0, you can include authoring information to your commits.

Authoring in unsigned commits

If you don’t enable commit signing:

If you add an author override, the author for every commit will be the configured override.
If you don’t select author override, the signed-in Grafana user name and email will be used as the commit author.

Authoring in signed commits

If you enable commit signing:

If you enable the signer as the commit author, Git Sync will use the signer name and email as the author to all commits.
If you don’t enable the signer as the commit author, the signed-in Grafana user name and email will be used as the commit author, and the committer will be the configured signer.

Check your dashboards in Grafana

Make sure that your synced dashboards are available at the location that you specified:

Go to Dashboards.
Look for the name of the dashboard in the Name column.

Now that your resources are synced, you can customize the name, change the branch, and create a pull request (PR) for it. Refer to Manage provisioned repositories with Git Sync for more information.

Update or delete your synced resources

To update or delete your repository configuration after you’ve completed setup:

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Select Administration > General > Provisioning.
Go to the Repositories tab, and locate the repository you want to modify.
Select Settings to access the Configure repository screen:

To modify your configuration, update any of the settings and select Save.
To delete the repository, click Delete. You can either keep the synced resources or delete them.

Next steps

You’ve successfully set up Git Sync to manage your Grafana dashboards through version control. Your dashboards are now synchronized with a GitHub repository, enabling collaborative development and change tracking.

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

Add non-provisioned resources from Grafana

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

Add non-provisioned resources from Grafana

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

You can add dashboards to Git Sync using any of the following options:

Add a dashboard using Import dashboards

You can import dashboards directly into your Git Sync provisioned folders using the Grafana UI or the HTTP API.

To access the Import dashboard tool from the Git Sync UI:

Go to the Dashboards tab of you connection.
On the top right corner, click New.
Select Import dashboard and you’ll be redirected to the wizard.
Upload or paste the dashboard JSON.
Fill in the relevant fields, including the branch and repository folder, and press Import.
Open the pull request, follow your regular workflow, and merge. Note that it could take a few minutes until the imported dashboard appears.

Keep in mind the following:

UIDs are globally unique per org. Two repositories with dashboards sharing a UID will conflict.
Two dashboards can share a title as long as they live at different paths in the repo. If a file with the same name already exists at the target path, the import is stopped before it overwrites anything.

For more information refer to Import dashboards in the Data Visualization documentation.

Note
It may take a few minutes for your changes to reflect on your screen. If they don’t, refresh the UI manually.

Copy an existing dashboard from the Grafana UI

You can also save a copy of dashboard directly from the Grafana UI to your provisioned folder.

To do so, follow these steps:

Make sure the dashboard is in Editable mode.
Select Save or Save as from the top-right corner.
In the menu:
- Target folder: Select the provisioned folder from your Grafana UI where you want to save the dashboard in.
- Branch: Type in the name of the branch of the provisioned repository you want to work in, or create a new branch. Committing directly to main is not supported.
- Folder: Type in the folder in your sync repository, if any.
- Fill in the rest of the fields accordingly.
Click Save.
In your synced GitHub repository, merge the branch with the dashboard you want to sync.

Add a dashboard with the Grafana CLI

You can also export an existing dashboard from the terminal or from agentic coding tools using the CLI gcx. With gcx you can download the resources you want to sync from Grafana, and then commit and push those files to your provisioned Git repository. Git Sync will then detect the commit, and synchronize with Grafana.

Note
For more information refer to the gcx documentation.

To add a dashboard with gcx, follow these steps:

Set up the gcx context to point to your instance as documented in Defining contexts.
Pull the resources you want to sync from the instance to your local repository:
```
gcx resources pull dashboards --path <REPO_PATH>
```
Commit and push the resources to your Git repository:
```
git add <DASHBOARDS_PATH>
git commit -m "Add dashboards from Grafana"
git push
```
Where:
- <GIT_REPO>: The path to the repository synced with Git Sync
- <DASHBOARDS_PATH>: The path where the dashboards you want to export are located. The dashboards path must be under the repository
Delete the original unmanaged resources you want to sync from Grafana. This step is required because Git Sync will not adopt a resource while an unmanaged resource with the same UID (metadata.name) still exists in Grafana.
Trigger a new pull to complete the sync. The resources are recreated as provisioned, with their original UIDs, so existing links keep working.

Note
Deleting resources implies certain operational caveats. Refer to How to delete existing resources in Grafana for more information.

Add a dashboard via JSON export

To add an existing dashboard to Git Sync via JSON export, you need to:

Export the dashboard as JSON.
Convert it to the Custom Resource Definition (CRD) format required by the Grafana App Platform.
Commit the converted file to your Git repository.
Delete the original unmanaged resources you want to sync from Grafana. This step is required because Git Sync will not adopt a resource while an unmanaged resource with the same UID (metadata.name) still exists in Grafana.
Trigger a new pull to complete the sync. The resources are recreated as provisioned, with their original UIDs, so existing links keep working.

Note
Deleting resources implies certain operational caveats. Refer to How to delete existing resources in Grafana for more information.

Required JSON format

To export a dashboard as a JSON file it must follow this CRD structure:

{
  'apiVersion': 'dashboard.grafana.app/v1',
  'kind': 'Dashboard',
  'metadata': { 'name': 'dcf2lve9akj8xsd' },
  'spec': { /* Original dashboard JSON goes here */ },
}

The structure includes:

apiVersion: Specifies the API version. Both classic and v2 JSON models are supported. For more information, refer to Dashboard JSON model.
kind: Identifies the resource type. For example, dashboard.
metadata: Contains the dashboard identifier uid. You can find the identifier in the dashboard’s URL or in the exported JSON.
spec: Wraps your original dashboard JSON.

How to delete existing resources in Grafana

If you add existing resources using gcx or via JSON import, the resource UID is kept, so you need to manually delete the original resource in Grafana to provision it with Git Sync.

When you delete a resource, keep in mind the following:

You cannot restore deleted resources from the UI.
Dashboard version history does not carry over.
You need to reapply custom folder permissions. Refer to Git Sync permissions and access control for more details.
Git Sync does not support alerts for the moment.
Deleting a folder deletes its alert rules. Move them out before deleting the folder.

Work with Git-managed dashboards

After you’ve saved a dashboard in Git, it’ll be synchronized automatically, and you’ll be able to work with it as any other provisioned resource. Refer to Work with provisioned dashboards for more information.

Work with provisioned repositories in Git Sync

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

Work with provisioned repositories in Git Sync

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

After you sync your resources, Git Sync creates a dashboard that provides a summary of resources, health, pull status, webhook, sync jobs, resources, and files. To access it, follow these steps:

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Select Administration > General > Provisioning in the left-side menu to access the Git Sync configuration screen.
Go to the Repositories tab, and locate the repository you want to work with. You can view the current status of the sync, run pulls, or update your settings.

Refer to Work with provisioned dashboards for more information about working with provisioned files.

View the current status of your synchronized repository

Use the View section to see detailed information about the current status of your sync and troubleshoot possible issues:

The Overview tab contains information about the health of your repository’s connection with Grafana, configuration options such as webhooks, or information on Git processes.
The Resources tab lists the provisioned resources of the connection.

Troubleshoot synchronization

Note
Before you proceed to troubleshoot, understand the Usage and performance known limitations.

Monitor the View status page for synchronization issues and status updates. The status page displays the following events:

Sync started: The synchronization process has begun.
Sync completed: The synchronization process finished successfully.
Sync failed: The synchronization process failed. Refer to the error details for troubleshooting.
Sync issues: The synchronization process encountered issues.

Dashboard sync errors

Repository URL: If dashboards don’t sync, verify that the repository URL is correct and accessible from the Grafana instance.
Repository branch: Verify that the configured repository branch exists and is correctly referenced.
Conflicts: Check for conflicts in the repository that may prevent syncing.

Dashboard import errors

Validate the JSON format of the dashboard files before importing.
If the import fails, check Grafana logs for error messages and troubleshoot accordingly.

Synchronize changes

To sync resources between the provisioned repositories and your Grafana instance, click Pull under the repository you want to sync. The synchronization process runs and completes.

Grafana overwrites existing dashboards with the same uid.

Update or delete your settings

To update or delete your repository configuration after you complete setup:

Log in to your Grafana server with an account that has the Grafana Admin flag set.
Select Administration > General > Provisioning.
Go to the Repositories tab, and locate the repository you want to modify.
Select Settings to access the Configure repository screen:

To modify your configuration, update any of the settings and select Save.
To delete the repository, click Delete. You can either keep the synced resources or delete them.

Note
It may take a few minutes for your changes to reflect on your screen. If they don’t, refresh the UI manually.

Manage folder permissions

By default, users keep their roles in folders provisioned with Git Sync.

Grafana Role	Folder Permission
Admin	Admin
Editor	Editor
Viewer	Viewer

Refer to Git Sync permissions to understand and set up permissions in Git Sync.

Modify folder permissions

Note
To modify permissions, each provisioned folder must include the _folder.json metadata file, which gives the folder a stable UID. Without it, the folder’s permissions are lost if you move or rename that folder in the Git repository. Refer to The Git Sync folder metadata file for details about this file and why it exists.

Folder permissions attach to the folder’s UID (stored in _folder.json), not to its repository path, so you can only set them after Git Sync has created the folder. To add or modify folder permissions:

From the UI, select Folder actions > Manage permissions on the top right corner.
Using the API, refer to Dashboard Permissions API.
As code with Terraform, using the folder UID from _folder.json. Refer to Modify folder-level permissions for manual and Terraform examples.

The Git Sync folder metadata file

Each provisioned folder in a synced repository contains a _folder.json metadata file at its root. This file is the folder’s manifest: it stores the folder’s stable UID and its display name, so both survive changes to the repository layout.

The file exists because a directory path isn’t a stable identity. Without _folder.json, Grafana derives the folder UID from a hash of the directory path in the repository. If you move or rename that directory in Git, the hash changes and Grafana treats it as a different folder: everything attached to the old UID, such as custom folder permissions, bookmarks, and API references, is lost. With _folder.json, the UID travels with the directory, so you can reorganize your repository without breaking permissions or references.

The file also separates the folder’s display name from the directory name. The directory keeps a filesystem-friendly name, for example team-platform, while the spec.title field holds the name shown in the Grafana UI, for example Team Platform.

Grafana manages this file for you:

When you create a provisioned folder from the Grafana UI, Git Sync commits the _folder.json file together with the folder.
When you rename a folder in Grafana, Git Sync updates the spec.title field in the file.
If a folder is missing the file, for example because you created the directory directly in Git, Grafana falls back to the hash-derived UID and shows a warning in the UI with instructions on how to add the missing metadata.

The file has the following format:

{
  "apiVersion": "<API_VERSION>",
  "kind": "Folder",
  "metadata": {
    "name": "<FOLDER_UID>"
  },
  "spec": {
    "title": "<FOLDER_UI_NAME>"
  }
}

Where:

<API_VERSION> is the version of the folders API. For example, folder.grafana.app/v1.
<FOLDER_UID> is the stable folder UID that Grafana uses for permissions, bookmarks, and API references. Treat this value as immutable: Grafana rejects folder UID changes, and changing it directly in Git breaks the link between the directory and the existing Grafana folder, with the same consequences as having no metadata file.
<FOLDER_UI_NAME> is the display name shown in the Grafana UI. This field is optional. If it’s not set, Grafana uses the directory name instead.

Work with provisioned dashboards in Git Sync

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

Work with provisioned dashboards in Git Sync

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

Using provisioning, you can choose to store your dashboard JSON files in either Git repositories using Git Sync or a local path, and manage them through the Grafana interface. Dashboards and folders synchronized using Git Sync or a local path are referred to as provisioned resources. Git Sync is the recommended method for provisioning your dashboards.

Manage dashboards provisioned with Git Sync

Using Git Sync, you can manage your dashboards in the UI and synchronize them with your configured Git repository. If you push a change in the repository, those changes are mirrored in your Grafana instance.

Dashboards saved in your repository or local folder configured with Git Sync appear in a provisioned folder in Grafana.
Any dashboard folders saved with Git Sync have a Provisioned label in the UI.
To save any changes to provisioned resources, open a pull request or commit directly to an existing branch, such as the main branch.
- Use pull requests to review changes to dashboards.
- Preview the changes before merging.

Refer to Key concepts for more details.

Create a new dashboard

Note
It may take a few minutes for your changes to reflect on your screen. If they don’t, refresh the UI manually.

You have the following options to add new dashboards in your Git Sync connection:

Create them directly within Git Sync-managed folders in the Grafana UI
Add them by committing JSON files to your Git repository

If you want to add an existing dashboard to your provisioned resources, refer to Export non-provisioned resources from Grafana.

Add a new dashboard from the Grafana UI

To add a new dashboard from the Grafana UI:

On the Dashboards tab, click on New on the top right corner and chose one of these options:
- New dashboard. When you create a new dashboard in a provisioned folder associated with a Git repository, you follow the same process you use for any new dashboard. Refer to Create a dashboard for more information.
- Import dashboard. Refer to Add a dashboard using Import dashboards for more details.
- Use template. Create a dashboard using a Grafana template.

After you create the dashboard, follow these steps:

Click Save dashboard.
On the Provisioned dashboard panel, choose the options you want to use:
- Title: The title of the dashboard.
- Description: Description of the dashboard.
- Target folder: The folder where you want to store the new dashboard.
- Branch: Specify the branch name in your Git provider (for example, main).
- Repository folder: The folder inside the repository. Leave empty for the repository root.
- Filename: The name of the dashboard file.
- Comment: Add a comment describing your changes for you commit.
Optional: Select the Changes tab to view the differences between the updates you made and the original resource.
Select Save, and the updated dashboard will load.
On the prompt, select Open a pull request in GitHub to open a new PR to your repository.
Follow your usual Git workflow to save and merge the PR to your repository.

Edit dashboards

When you edit a provisioned resource, you’re prompted to save or discard those changes. Saving changes requires opening a pull request in your Git repository.

To save dashboard changes:

Select Edit to update a provisioned dashboard.
Make your desired changes, and click Save dashboard.
On the Provisioned dashboard panel, choose the options you want to use:
- Branch: Specify the branch name in your Git provider (for example, main).
- Repository folder: The folder inside the repository. Leave empty for the repository root.
- Filename: The name of the dashboard file.
- Comment: Add a comment describing your changes for your commit.
Optional: Select the Changes tab to view the differences between the updates you made and the original resource.
Select Save, and the updated dashboard will load.
On the prompt, select Open a pull request in GitHub to open a new PR to your repository.
Follow your usual Git workflow to save and merge the PR to your repository.

Remove dashboards

You can remove a provisioned dashboard by deleting the dashboard from the repository. The Grafana UI updates when the changes from the Git repository sync.

To restore a deleted dashboard, raise a PR directly in your Git repository. Restoring resources from the UI isn’t possible at the moment.

Document folders with a README

You can document the contents or any other relevant piece of information of your provisioned folder in a README.md file stored alongside its resources in the repository. Grafana renders the README inline on the folder page, below the list of dashboards, so your team can see what’s in the folder, how it’s organized, and where to find the right dashboard without leaving Grafana.

When the folder contains a README.md file, Grafana renders its Markdown content. Relative links and images in the README resolve against the host repository.
If the folder has no README.md, or if the folder is empty, you’ll be prompted to action with a Add README button.
You can edit the README any time. Select the edit pencil in the README header to open the file in your Git provider’s editor and commit changes through your usual workflow.

Note
It may take a few minutes for your changes to reflect on your screen. If they don’t, refresh the UI manually.

Best practices

Follow these recommendations when working with provisioned dashboards:

Use GitHub pull requests for changes: Maintain review processes for dashboard modifications.
Provide clear commit messages: Describe your changes to help with tracking and collaboration.
Regularly sync your repository: Keep Grafana up to date with the latest changes.
Review the Events tab: Monitor sync status to ensure changes are applied correctly.
Add a folder README: Document each folder’s contents with a README.md so your teammates can find the right dashboard quickly.

Refer to Work with provisioned repositories for general guidance about using Git Sync.

Git Sync permissions and access control

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

Git Sync permissions and access control

For Git Sync to work correctly you need to configure permissions at two layers:

At the Grafana level for repository management and resource access, as described in this document.
At your Git provider level, to protect your repository. Refer to Repository protection for Git Sync for more information.

Grafana role-based permissions

Git Sync integrates with the Grafana standard role-based permission model, which has three levels:

Organization-level: Default permissions of the Admin, Editor, or Viewer role. Refer to Roles and permissions for more details.
Folder-level: They also apply to all dashboards within it. Refer to Folder permissions for more details.
Dashboard-level: Refer to Dashboard permissions for more details.

Note
Dashboard-level permissions override folder-level permissions, which override organization-level roles.

The following applies for Git Sync:

Permissions don’t sync: Folder and dashboard permissions are managed in Grafana only and don’t sync to Git. You must configure permissions separately in each Grafana instance that uses the repository
Dashboard changes: When users with appropriate dashboard or folder permissions modify dashboard content, those changes automatically sync to Git, or create pull requests if branch protection is enabled
Folder structure: Creating, renaming, or deleting folders syncs to Git

Use org-level permissions in Git Sync

If you apply org-level permissions, users can do the following with Git Sync:

Admin users

If Grafana OSS/Enterprise, you need to have the Admin role to set up and manage Git Sync repositories and connections. In Grafana Cloud, the equivalent role is Grafana Cloud Admin or Admin at the organization level.

As an Admin you can:

Configure new Git Sync repositories and connections
Update repository settings (URL, branch, path, sync interval, webhook configuration)
Delete repository connections
Manage authentication credentials and Git provider connections
Manually trigger sync operations (pull from Git)
View sync status, logs, and statistics
Access the Provisioning admin UI at Administration > General > Provisioning

Editor users

Users with the Editor role can work with provisioned dashboards and folders. Their specific capabilities depend on the folder-level and dashboard-level permissions assigned to them.

Organization-level capabilities:

View dashboard preview links in pull requests
Push their dashboard and folder changes to Git, including opening pull requests, via the jobs API

Note
Only Admins can trigger a manual sync (pull from Git) and orphan-resource clean-up. Editors can push their own changes but can’t pull from Git on demand. Refer to Job actions and required permissions for more details.

Resource access depends on folder/dashboard permissions:

Folder Editor or Admin: Create, edit, and delete dashboards within the folder; create subfolders; changes sync to Git
Folder Viewer: View dashboards only within that folder
Dashboard Editor or Admin: Edit specific dashboards; changes sync to Git (even without folder edit access)
Dashboard Viewer: View specific dashboards only

Editors don’t need access to the Provisioning admin UI or repository configuration. Refer to Configure folder and dashboard permissions and Configure fine-grained access control (RBAC) for details.

Viewer users

Users with the Viewer role can view provisioned resources. Their access to specific dashboards and folders depends on the permissions assigned to them.

Organization-level capabilities:

Read Git Sync settings, via the provisioning.settings:read permission
View dashboard preview links in pull requests

Resource access depends on folder and dashboard permissions:

Folder Viewer: View all dashboards and subfolders within that folder
Dashboard Viewer: View specific dashboards (even if they don’t have folder access)
Cannot edit dashboards or manage Git Sync repositories

Configure folder and dashboard permissions

Folder-level role permissions determine who can view, edit, or delete provisioned resources.

These roles grant Grafana permissions (dashboards:read, dashboards:write, folders:create…) that are checked when users interact with provisioned resources through the Git Sync files endpoint. Dashboards within a provisioned folder inherit the folder’s permissions.

When Git Sync creates a provisioned folder, it assigns these default permissions:

Grafana Role	Folder Permission
Admin	Admin
Editor	Editor
Viewer	Viewer

Folder-level Viewer users:

View dashboards and folders
Cannot create, edit, or delete resources

Folder-level Editor users:

Have all Viewer permissions
Create, edit and delete dashboards
Create subfolders
When an Editor saves dashboard changes, Git Sync automatically commits the changes to Git, or creates a pull request if branch protection is enabled

Folder-level Admin users:

Have all Editor permissions
Update folder settings, rename and delete folders
Modify folder permissions
Full control over the folder and all its contents

Modify folder-level permissions

Folder permissions in Grafana are attached to a folder’s UID, not to its path in the Git repository. Git Sync stores this UID in the folder’s _folder.json metadata file (in the metadata.name field). For the metadata file schema and why it exists, refer to The Git Sync folder metadata file.

Because permissions reference the folder UID, keep the following in mind:

Create the folders first. A folder must exist in Grafana—and have a _folder.json file with a stable UID—before you can assign permissions to it. Let Git Sync create and sync the folders, then apply the permissions that reference the resulting UIDs. If you try to set a permission for a folder that hasn’t been synced yet, there’s no UID to attach it to.
Permissions don’t sync to Git. You set them per Grafana instance. Every instance that syncs the same repository shares the same folder UIDs (from _folder.json), so you can apply the same permission definitions to each instance.

Note
To safely modify permissions, each provisioned folder must include a _folder.json metadata file with the folder’s UID. Without this file, the folder’s UID is derived from its repository path, so folder permissions can be lost if the folder is moved to a different path in the Git repository.

For folders created from the Grafana UI, the metadata file is added automatically. If your folder is missing the metadata file, the UI shows a warning with instructions on how to add it. Refer to The Git Sync folder metadata file for details about this file and why it exists.

You can set folder permissions manually or as code. In both cases, apply them only after Git Sync has created the folders.

Set permissions manually

Grafana UI: Navigate to the folder and select Folder actions > Manage permissions. Add or edit permissions for roles, teams, or users.
HTTP API: Use the Folder/Dashboard permissions API. Reference the folder by the UID stored in its _folder.json file.
RBAC (Enterprise/Cloud): Use Role-Based Access Control for fine-grained permission management.

Set permissions with Terraform

You can manage folder permissions as code with the Grafana Terraform provider. Because Git Sync—not Terraform—creates the folders, reference each folder by the UID from its _folder.json file (the metadata.name value). Apply the permissions only after Git Sync has synced the folders, so the folder UIDs already exist.

Use grafana_folder_permission_item to manage a single permission entry. This is additive, so it only manages the entries you declare and leaves other permissions untouched:

# The UID comes from the folder's _folder.json metadata file ("metadata.name").
locals {
  team_platform_folder_uid = "team-platform-abc123"
}

resource "grafana_folder_permission_item" "team_platform_editor" {
  folder_uid = local.team_platform_folder_uid
  team       = grafana_team.platform.id # an existing team
  permission = "Edit"
}

resource "grafana_folder_permission_item" "team_platform_viewer" {
  folder_uid = local.team_platform_folder_uid
  role       = "Viewer"
  permission = "View"
}

Alternatively, use grafana_folder_permission to declare the full set of permissions for a folder in a single resource. This resource is authoritative: any permission that isn’t listed is removed when you apply the configuration.

Note
Don’t manage these folders with the grafana_folder resource—they’re owned by Git Sync. To avoid hardcoding UIDs, read them from the _folder.json files in your repository, or look them up with a grafana_folder data source.

Configure fine-grained access control (RBAC)

If you’re a Grafana Enterprise or Grafana Cloud user with RBAC enabled, Git Sync provides fine-grained permissions that allow more granular control over Git Sync operations. You can create custom roles that combine Git Sync permissions in different ways. Refer to Role-Based Access Control documentation for instructions on creating and managing custom roles.

How basic roles map to RBAC permissions

Understanding which permissions each basic role receives helps you create custom roles or understand exactly what access users have. The tables below show which Git Sync permissions are granted to each role by default.

Note
The provisioning.settings:read permission is granted to all roles (Viewer and above) and allows viewing Git Sync system settings, which is necessary for the UI to display properly. This does not grant access to modify settings or manage repositories.

Admin role

Users with the Admin role receive full access to Git Sync infrastructure:

Permission Category	Specific Permissions	What This Allows
Repositories	`provisioning.repositories:create` `provisioning.repositories:read` `provisioning.repositories:write` `provisioning.repositories:delete`	Create new repositories View repository configurations Update repository settings (branch, path, interval) Delete repositories
Connections	`provisioning.connections:create` `provisioning.connections:read` `provisioning.connections:write` `provisioning.connections:delete`	Create Git provider connections View connection details Update connection settings Delete connections
Jobs	`provisioning.jobs:create` `provisioning.jobs:read` `provisioning.jobs:write` `provisioning.jobs:delete`	Trigger manual syncs View sync jobs Modify sync job settings Cancel/delete sync jobs
History & Monitoring	`provisioning.historicjobs:read` `provisioning.stats:read`	View sync job history View Git Sync statistics and metrics
Settings	`provisioning.settings:read`	View Git Sync system settings

Editor role

Users with the Editor role can manage sync operations but not infrastructure configuration:

Permission Category	Specific Permissions	What This Allows
Jobs	`provisioning.jobs:create` `provisioning.jobs:read` `provisioning.jobs:write` `provisioning.jobs:delete`	Push changes and open pull requests View sync jobs Modify sync job settings Cancel/delete sync jobs
Read-Only Access	`provisioning.repositories:read` `provisioning.settings:read`	View repository configurations View Git Sync settings

Note
provisioning.jobs:create allows editors to create jobs to push their changes, subject to the relevant dashboards:* and folders:* permissions. However, it doesn’t allow admin-only job actions such as a manual pull from Git or orphan-resource cleanup, which require the provisioning.repositories:write permission. Refer to Job actions and required permissions for more details.

Editors can access resources based on the folder/dashboard assignments:

dashboards:create, dashboards:read, dashboards:write, dashboards:delete - On folders/dashboards where assigned Folder Editor or Dashboard Editor
folders:create, folders:read, folders:write, folders:delete - On folders where assigned Folder Editor

Viewer role

Users with Viewer role have read-only access to Git Sync:

Permission Category	Specific Permissions	What This Allows
Read-Only Access	`provisioning.repositories:read` `provisioning.settings:read`	View repository configurations View Git Sync settings (required for UI)

Viewers can access resources based on the folder/dashboard assignments:

dashboards:read - On folders/dashboards where assigned Folder Viewer or Dashboard Viewer
folders:read - On folders where assigned Folder Viewer

RBAC for dashboards and folders

Provisioned dashboards and folders use the Grafana standard permission model. To modify provisioned resources, you will need permissions over your dashboard and folder.

The following applies for Git Sync:

You need standard dashboards:* and folders:* permissions to work with provisioned resources
Editors and Viewers need provisioning.settings:read and provisioning.repositories:read to view Git Sync configuration
You do not need repository write/delete or connection permissions to edit dashboards
Dashboard-level permissions override folder-level permissions
Changes made by users with appropriate permissions automatically sync to Git

Job actions and required permissions

Git Sync operations run as jobs. You need the provisioning.jobs:create permission to create any job. Moreover, some job actions are restricted to administrators and require the provisioning.repositories:write permission. This prevents editors from triggering repository-wide operations even though they hold provisioning.jobs:create.

Job action	Required permission	Who can run it
Push changes / open pull request	`provisioning.jobs:create` plus the relevant `dashboards:` / `folders:` permissions	Editors and Admins, on the resources they can modify
Migrate resources	`provisioning.jobs:create` plus read/write on the affected resource types	Editors and Admins with the required resource permissions
Manual sync (pull from Git)	`provisioning.repositories:write`	Admins only
Release / delete orphaned resources	`provisioning.repositories:write`	Admins only

Repository subresource access

The repository API exposes several subresources. The following table shows the permission each one is gated on.

The refs subresource lists the repository’s branches and commits, and two distinct flows legitimately need it:

Editors pushing changes: When an editor saves changes or opens a pull request through the push-job flow, Grafana needs the branch list. This is authorized with provisioning.jobs:create.
Admins configuring a repository: When an admin or repository owner sets up or edits a repository and picks a target branch, Grafana updates the Repository resource info. This is authorized with provisioning.repositories:write.

Because the repositories resource has no Editor tier (repositories:read is granted to Viewer and above, while write, create, and delete are admin-only), refs accepts either of these checks, and viewers satisfy neither.

Subresource	Purpose	Required permission	Who can access it
`files`	Read and write provisioned resource files	Authenticated access, then standard `dashboards:` / `folders:` checks	All authenticated users
`refs`	List repository branches and commits	`provisioning.repositories:write` or `provisioning.jobs:create`	Admins and Editors
`resources`, `history`, `status`	Repository management and inspection views	`provisioning.repositories:write`	Admins only

Note
The management and inspection views (resources, history, status) are gated on provisioning.repositories:write rather than repositories:read, because there’s no admin-only read action on the repositories resource. As a result, only users who can manage a repository can inspect its management views; Viewers and Editors can’t access these views.

Configure Git repository protection

After you’ve configured your Grafana permissions, set up the appropriate permissions at your Git provider to write changes. Repository protection settings control write access, branch protection rules, and code review requirements.

For detailed information about configuring repository write access and branch protection, refer to Repository protection for Git Sync.

Troubleshoot permissions

“Permission denied” when saving a dashboard

Cause: User lacks Editor or Admin permission on the provisioned folder.

Solution:

Verify the user’s folder-level permissions in Grafana
Navigate to Folder settings > Permissions
Grant the user or their team Editor or Admin role

Git Sync fails with “403 Forbidden” or “Unauthorized”

Cause: The Git provider authentication credentials lack the required repository permissions.

Solution:

Verify the authentication credentials (GitHub App, Personal Access Token) have read and write permissions on the repository
If using a GitHub App or OAuth app, verify it is installed and authorized for the target repository
Check that the credentials have permission to create pull requests (if branch protection is enabled)
Verify authentication credentials haven’t expired
For expired or revoked tokens, generate new credentials and update the Git Sync connection configuration

Dashboard changes commit directly instead of creating pull requests

Cause: Branch protection is not configured at the Git provider.

Solution: Enable branch protection rules at your Git provider to enforce pull request workflows or in your Grafana repository settings. Refer to your Git provider’s documentation for instructions on configuring branch protection.

Dashboard changes commit directly without review

Cause: Branch protection is not configured at the Git provider.

Solution:

Enable branch protection on the target branch at your Git provider
Configure the branch to require pull requests before merging
Verify the branch name in protection rules matches the branch configured in Grafana

Pull requests not created when expected

Cause: Branch protection is not enabled or the authentication credentials lack pull request creation permission.

Solution:

Verify branch protection is enabled on the correct branch
Check that the credentials have permission to create pull requests
Ensure the branch name in Git Sync settings matches the protected branch exactly

Configure Git repository protection

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

Configure Git repository protection

For Git Sync to work correctly you need to configure permissions at two layers:

At your Git provider level, to protect your repository, as described in this document.
At the Grafana level for repository management and resource access. Refer to Git Sync permissions and access control for more information.

When you use Git Sync, your dashboard configurations are stored as code in a Git repository. You can configure Git repository protection to control who can access this source code and who can modify it. Repository protection works as an additional security layer after Grafana internal permissions.

Required permissions at the Git provider level

Git Sync authentication credentials must have specific permissions at your Git provider:

Required for all configurations:

Read access to repository contents
Read access to branch information

Required for writing changes:

Write access to create commits
Permission to create pull requests (when branch protection is enabled)
Permission to push to feature branches (for creating pull requests)

Optional for instant synchronization:

Permission to create and manage webhooks

Refer to the Git Sync setup documentation for detailed instructions on configuring authentication for your Git provider.

Control access to the dashboards source code

You can access dashboard source code through two paths, each with its own protection mechanism:

Grafana files endpoint: Users can view and edit dashboard source code through the Grafana files API endpoint. Use Grafana folder and dashboard permissions to control this access. Refer to Manage access to dashboard source code via the API for more information.
Git repository: Users with repository access can view and modify dashboard files directly in Git. You can control repository permissions in your Git provider. Refer to Control access to your Git repository for more information.

Protect both access points to secure your dashboard configurations.

Manage access to dashboard source code via the API

View dashboard source code

You can view dashboard source code through the files endpoint if you have Viewer permission or higher on the dashboard or its parent folder. This allows you to:

List files in provisioned folders and branches
Read dashboard JSON content
View folder structure and organization

Edit dashboard source code

You can modify dashboard source code through the files endpoint if you have Editor or Admin permission on the dashboard or its parent folder. This allows you to:

Create new dashboard files
Update existing dashboard content
Delete dashboards
Modify folder structure

When you save changes through this endpoint, Git Sync commits those changes to the Git repository (or creates pull requests if branch protection is enabled), subject to Git repository permissions.

For detailed information about configuring folder and dashboard permissions in Grafana, refer to Git Sync permissions and access control.

Control access to your Git repository

Access control at the Git provider level determines who can view and modify your dashboard source code. Configure repository access based on your security and compliance requirements.

Read access (repository visibility)

Read access controls who can view the dashboard source code stored in your repository. This includes dashboard JSON files, folder structure, and any other files in the repository.

Public repositories: Anyone can view the repository contents, including dashboard configurations and any data or queries they contain. Only use public repositories if your dashboards contain no sensitive information.

Private repositories: Only authorized users can view repository contents. This protects dashboard configurations, queries, and any embedded credentials or sensitive data from public access.

For Git Sync to function, the authentication credentials configured in Grafana must have read access to pull dashboard changes from Git to Grafana.

Write access (push permissions)

Write access controls who can push changes to your repository. This determines who can modify dashboard source code, either directly or through pull requests.

Direct write access: Users with write permission can push commits directly to branches. For Git Sync to push dashboard changes from Grafana to Git, the authentication credentials must have write access to the repository.

Protected branches: Branch protection rules can restrict direct writes and require changes to go through pull requests with review and approval, even for users with write access.

Refer to the Git Sync setup documentation for detailed instructions on configuring authentication for your Git provider.

Control how changes are written in Git Sync

Git Sync supports different modes for writing dashboard changes to your repository, from allowing direct commits to requiring formal review processes.

Read-only mode

Configure the repository as read-only in Grafana to prevent any writes to Git from the Grafana UI. Dashboards sync from Git to Grafana, but users cannot save changes back to Git.

Use when: Git is the single source of truth and all changes must be made through direct Git commits or CI/CD processes.

Direct commit mode

When the repository allows writes and branch protection is not enabled, Git Sync commits dashboard changes directly to the configured branch without review.

Use when: Rapid iteration is needed and changes don’t require formal review, such as in development environments.

Pull request mode

When branch protection is enabled at your Git provider, Git Sync creates pull requests instead of committing directly. Changes require review and approval before merging to the main branch.

Use when: Changes require review and approval, such as in production environments or when multiple teams collaborate on dashboards.

Protect your branch

Branch protection rules at your Git provider enforce how changes are made to specific branches. When enabled on the branch that Git Sync targets, these rules require Git Sync to create pull requests instead of pushing commits directly.

Common use cases for branch protection:

Production environments requiring change approval
Compliance requirements for audit trails and review
Multi-team environments where changes need visibility

Branch protection can enforce various controls such as requiring pull requests before merging, setting reviewer approval requirements, running automated validation checks, preventing force pushes, and restricting who can push directly to protected branches.

Refer to your Git provider’s documentation for specific instructions on configuring branch protection rules.

Code review assignments

Many Git providers support CODEOWNERS files that automatically assign reviewers to pull requests based on which files are changed. When Git Sync creates a pull request, the Git provider can use the CODEOWNERS file to assign the appropriate team or users for review.

This ensures dashboard changes are reviewed by the teams responsible for those dashboards, based on folder path or file patterns.

Refer to your Git provider’s documentation for instructions on configuring CODEOWNERS files.

Troubleshooting

For permissions troubleshooting refer to Troubleshoot permissions in the Git Sync permissions documentation.

Git Sync deployment scenarios

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

Git Sync deployment scenarios

Note
Git Sync functionalities are constantly evolving. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

This guide shows practical deployment scenarios for Grafana’s Git Sync. Learn how to configure bidirectional synchronization between Grafana and Git repositories for teams, environments, and regions.

Learn more

Refer to the following documents to learn more: