Introduction to Git Sync on Grafana Labs

Git Sync Key concepts

Thu, 23 Apr 2026 11:39:03 +0000

Git Sync key concepts

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

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

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.

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

Wed, 13 May 2026 14:28:21 +0000

Usage and performance limitations

Note
Git Sync is now GA for Grafana Cloud, OSS and Enterprise.

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

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	10
Amount of synced resources per repository	20	1,000	No limit	No limit

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.

If you’re a Cloud user, contact Support to modify the amount of repositories you can sync.

If you’re an on-prem user, you can customize your limits via configuration settings:

Use max_repositories to set the amount of repositories you can sync. 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. Refer to max_resources_per_repository in the Configure Grafana section to learn more.

Nested folders

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

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

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, 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 enables richer pull request workflows, deeper linking between Grafana and GitHub, and tighter integration into review processes. It is available in Grafana OSS, Enterprise, and Cloud.

Note
GitHub Enterprise Server is currently only supported through the Pure Git repository type. A dedicated enhanced integration for GitHub Enterprise Server is planned for upcoming releases.

The GitLab and Bitbucket integrations have limited functionality for the moment, and are only available in Grafana Enterprise and Grafana Cloud. Expect continued improvements around pull request workflows, linking, and sync behavior in upcoming releases.

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.

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.

When migrating existing dashboards, the folder structure will be replicated in the repository. You may need to manually remove or manage original folders after the migration.

Use existing resources

If you want to manage existing resources with Git Sync, you can 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.

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

Wed, 29 Apr 2026 10:14:30 +0000

Set up Git Sync

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

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

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, verify your dashboards.
Optionally, you can also extend Git Sync with webhooks and image rendering.

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, GitLab and Bitbucket. Refer to Compatible providers for more details.

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.

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.

Note
If you’re using self-hosted GitHub servers or GitHub Enterprise refer to Configure with Pure Git for instructions on how to set up Git Sync.

Connect with a GitHub Personal Access Token

If you want to configure Git Sync for GitHub and authenticate with a Personal Access Token, sign in to GitHub and create a new fine-grained personal access token with these permissions:

Administration: Read-only permission (enables validation of branch protection rules against the configured branch when users can push directly to it; may be used in the future to check other repository settings and make the setup process smoother)
Contents: Read and write permission
Metadata: Read-only permission
Pull requests: Read and write permission
Webhooks: Read and write permission

Note
The Personal Access Token must belong to a user with the Admin role on 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.

Refer to Managing your personal access tokens for instructions.

Return to Grafana and fill in the following fields:

Paste your GitHub personal access token into Enter your access token.
Paste the Repository URL for your GitHub repository into the text box.

Select Configure repository to set up your provisioning folder.

Connect with GitHub App

Note
Refer to Create a GitHub App for instructions on how to create a 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:
1. Select Choose an existing app.
2. Click on the existing connection you want to use, and click on Configure repository to proceed.
3. Paste the Repository URL for your GitHub repository into the text box.
If you want to connect using a new GitHub App:
1. Select Connect to a new app.
2. Type in the following fields:
  - The ID of the GitHub App you want to use
  - The GitHub Installation ID
  - The Private Key
3. Click on Configure repository to proceed.
4. Paste the Repository URL for your GitHub repository into the text box.

Note that your GitHub App must have the following permissions:

Administration: Read-only permission (enables validation of branch protection rules against the configured branch when users can push directly to it; may be used in the future to check other repository settings and make the setup process smoother)
Contents: Read and write permission
Metadata: Read-only permission
Pull requests: Read and write permission
Webhooks: Read and write permission

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 and write 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 GitLab repository into the text box.

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

On this screen, you will sync the external resources you specified in the previous step with your Grafana instance. These provisioned resources will be stored in a new folder in Grafana without affecting the rest of your instance.

To set up synchronization:

Select the external storage you want to sync with your Grafana instance. 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.

Note
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

In this screen:

Review the known limitations before proceeding.
Check the Migrate existing resources box to migrate your unmanaged dashboards to the provisioned folder. If you select this option, all future updates are automatically saved to the synced Git repository and provisioned back to the instance.
Click Begin synchronization to create the Git Sync connection.

After the process is completed, you will 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 the Sync interval (seconds) to indicate how often you want your Grafana instance to pull updates from GitHub. The default value is 300 seconds in Grafana Cloud, and 60 seconds in Grafana OSS/Enterprise.

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.

Select Finish to complete the setup.

Verify your dashboards in Grafana

To verify that your dashboards are available at the location that you specified, go to Dashboards. The name of the dashboard is listed in the Name column.

Now that your dashboards have been synced from a repository, 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

Thu, 23 Apr 2026 11:39:03 +0000

Export non-provisioned resources from Grafana

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

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

Traditional operations such as moving or copying a dashboard to a provisioned folder or bulk export are gradually being incorporated into Git Sync. In the meantime the following options are available:

Add an existing dashboard from the Grafana UI

You can 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 Grafana CLI

You can also export an existing dashboard with gcx, the Grafana CLI. Use gcx to 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.

To do so, 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>

Next, 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

See more at Manage resources with Grafana CLI.

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.

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 (currently v1)
kind: Identifies the resource type (Dashboard)
metadata: Contains the dashboard identifier uid. You can find the identifier in the dahsboard’s URL or in the exported JSON
spec: Wraps your original dashboard JSON

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

Wed, 13 May 2026 11:49:28 +0000

Work with provisioned repositories in Git Sync

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

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

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 synchronization

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.

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 with the folder’s UID, which defines a stable folder ID used to set folder permissions. Without it, the folder’s permissions will be lost if you move that folder to a different path in the Git repository.

For new provisioned folders managed with Git Sync, the metadata file is added automatically if you created the folder from the Grafana UI. If your folder is missing the metadata file, you’ll see a warning in the UI with instructions on how to add the missing metadata.

You can modify folder permissions:

From the UI, refer to Manage dashboard permissions.
Using the API, refer to Dashboard Permissions API.

The Git Sync folder JSON metadata file

Each folder in a synced repository contains a .folder.json file at its root:

{
  "apiVersion": "folder.grafana.app/v1beta1",
  "kind": "Folder",
  "metadata": {
    "name": "<FOLDER_UID>"
  },
  "spec": {
    "title": "<FOLDER_UI_NAME>"
  }
}

Where:

<FOLDER_UID> is the stable folder UID that Grafana uses for permissions, bookmarks, and API references.
<FOLDER_UI_NAME> is the display name shown in the Grafana UI. This parameter is optional. If not used, the folder name will be passed instead.

Work with provisioned dashboards in Git Sync

Thu, 23 Apr 2026 11:39:03 +0000

Work with provisioned dashboards in Git Sync

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

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

Using provisioning, you can choose to store your dashboard JSON files in either GitHub 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. For more information, refer to the Dashboards documentation.

Git Sync is the recommended method for provisioning your dashboards. You can synchronize any new dashboards and changes to existing dashboards to your configured GitHub repository. If you push a change in the repository, those changes are mirrored in your Grafana instance. Refer to Set up file provisioning to learn more about the version of local file provisioning in Grafana 12.

Manage dashboards provisioned with Git Sync

Using Git Sync, you can manage your dashboards in the UI and synchronize them with a GitHub repository. Refer to How it works for more details.

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.

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

Create a new dashboard

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

You have two options for creating new dashboards or folders in Git Sync:

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

When you create a new dashboard in a provisioned folder associated with a GitHub repository, you follow the same process you use for any new dashboard. Refer to Create a dashboard for more information.

After you create the dashboard, follow these steps:

Select Save to preserve the new dashboard.
Enter a title for the dashboard and a description.
Select the provisioned folder from the Folder drop-down list.
In Path, provide the path for your repository, ending in a JSON or YAML file.
For Workflow, select Push to main to make a Git commit directly to the repository or Push to a new branch to create a pull request.
- Branch: Specify the branch name in GitHub (for example, main). This option only appears if you select Push to a new branch.
Select Save.

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 GitHub repository.

To save dashboard changes:

Select Edit to update a provisioned dashboard. Make your desired changes.
Click Save dashboard.
On the Provisioned dashboard panel, choose the options you want to use:
- Update default refresh value: Check this box to make the current refresh the new default
- Update default variable values: Check this box to make the current values the new default
- Path: Provide the path for your repository, ending in a JSON or YAML file
- Workflow: Select Push to main to make a Git commit directly to the repository or Push to a new branch to create a pull request
- Branch: Specify the branch name in GitHub (for example, main). This option only appears if you select Push to a new branch
- Comment: Add a comment describing your changes
Optional: Select the Changes tab to view the differences between the updates you made and the original resource.
Select Save.
If you chose Push to a new branch, select Open a pull request in GitHub to open a new PR to your repository. GitHub opens with your dashboard’s code as the contents of the PR.
Follow your usual GitHub 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 GitHub repository sync.

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

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

Git Sync permissions and access control

Wed, 13 May 2026 11:49:28 +0000

Git Sync permissions and access control

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

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

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

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

Users with the Admin role can set up and manage Git Sync repositories and connections.

Note
In Grafana Cloud, the equivalent role is Grafana Cloud Admin or Admin at the organization level.

Capabilities:

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

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

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
Trigger manual sync operations via jobs API

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.

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

Note
To safely modify permissions, each provisioned folder should include a .folder.json metadata file with the folder’s UID. Without this file, folder permissions may 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.

You can customize folder permissions using:

Grafana UI: Navigate to the folder, click the settings icon, and select Permissions
RBAC (Enterprise/Cloud): Use Role-Based Access Control for fine-grained permission management

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`	Trigger manual syncs 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

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:

Users 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
Users 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

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 credentials lack the required permissions.

Solution:

Verify the authentication credentials (GitHub App, Personal Access Token, etc.) have read and write permissions on the repository
Check that the credentials have permission to create pull requests (if branch protection is enabled)
If using a GitHub App or OAuth app, verify it is installed and authorized for the target repository
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.

Configure Git repository protection

Thu, 23 Apr 2026 11:39:03 +0000

Configure Git repository protection

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

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

When you use Git Sync, your dashboard configurations are stored as code in a Git repository. Git repository protection controls who can access this source code and who can modify it. This guide explains how to configure repository access at your Git provider to protect your dashboard source code.

Note
Repository protection works as an additional security layer after Grafana internal permissions. For information about Grafana permissions, refer to Git Sync permissions and access control.

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

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

Cause: The authentication credentials lack the required repository permissions.

Solution:

Verify the credentials have read and write access to the repository
Check that the credentials can create pull requests (if branch protection is enabled)
Verify authentication credentials haven’t expired
For GitHub Apps, verify the app is installed and authorized for the repository

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

Git Sync deployment scenarios

Thu, 23 Apr 2026 11:39:03 +0000

Git Sync deployment scenarios

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

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

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: