This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation As code Observability as code Git Sync Work with provisioned dashboards

Work with provisioned dashboards in Git Sync

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

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:

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

1. Click Save dashboard.
2. 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.
3. Optional: Select the Changes tab to view the differences between the updates you made and the original resource.
4. Select Save, and the updated dashboard will load.
5. On the prompt, select Open a pull request in GitHub to open a new PR to your repository.
6. 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:

1. Select Edit to update a provisioned dashboard.
2. Make your desired changes, and click Save dashboard.
3. 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.
4. Optional: Select the Changes tab to view the differences between the updates you made and the original resource.
5. Select Save, and the updated dashboard will load.
6. On the prompt, select Open a pull request in GitHub to open a new PR to your repository.
7. Follow your usual Git workflow to save and merge the PR to your repository.

Preview banner

This section applies to Git repository connections (GitHub, GitHub Enterprise, GitLab, Bitbucket, and plain Git). It doesn’t apply to local file provisioning, which has no branches or pull requests.

Whenever you’re viewing a provisioned dashboard loaded from a branch other than your repository’s configured branch, Grafana shows a preview banner at the top of the page. You’ll see it right after you create, edit, delete, or move a dashboard from the Grafana UI, as well as when you open a dashboard from a pull request notification.

The banner’s title reflects what changed:

• A new resource has been created in a branch in your Git provider.
• A resource has been updated in a branch in your Git provider.
• A resource has been deleted in a branch in your Git provider.
• A resource has been moved in a branch in your Git provider.

In every case, the rest of your organization keeps seeing the version on the configured branch until the branch is merged — what you’re looking at is a private preview of your own change. The banner also shows the branch your change was pushed to and the branch it targets.

From the banner you can:

• Select Open a pull request (or View pull request, if one already exists) to open the pull request for this change, in a new tab.
• Select View saved version, when editing a dashboard that already exists in Grafana, to jump back to the version currently saved on the configured branch, so you can compare it against your draft.

If the branch behind the preview no longer exists in the repository, for example, the pull request was already merged or closed and its source branch deleted, selecting Open a pull request can’t take you to a live pull request. Grafana instead shows This branch no longer exists and offers two ways forward:

• Save to a new branch: Reopens the save form with your draft intact, so you can commit it to a new branch and open a new pull request.
• View the current version: Navigates to the dashboard as currently saved in Grafana, if it exists.

Remove dashboards

You can remove a provisioned dashboard either from the Grafana UI or from the repository:

• From the Grafana UI: Open the dashboard, go to its settings, and select Delete. On the Provisioned dashboard panel, choose the branch, comment, and other options the same way you would when editing a dashboard, then select Delete. On the prompt, select Open a pull request and follow your usual Git workflow to review and merge the change.
• From the repository: Delete the dashboard’s file directly in Git. The Grafana UI updates when the changes from the Git repository sync.

To restore a deleted dashboard, revert the deletion (or re-add the file) directly in your Git repository and raise a PR as usual. 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.

Common uses include:

• Runbooks: Document how to respond to an alert or investigate an incident, with links to the dashboards teammates need.

• Architectural diagrams: Show how the system a folder monitors fits together, using Mermaid diagrams that render inline.

• Onboarding guidelines: Explain what each dashboard is for and how a new team member should navigate the folder.

• 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’re prompted to action with an 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. When you have several documents, the edit pencil targets the document that’s currently open.

Browse multiple documents with tabs

A folder can hold more than one Markdown document. When it does, Grafana shows a tab for each document above the rendered content, similar to how a Git provider presents documentation files.

• Grafana lists any .md and .markdown files stored alongside the folder’s resources.
• The README, CONTRIBUTING.md, and SECURITY.md files appear first, in that order, when they’re present. All other documents follow in alphabetical order.
• The README renders by default. Select a tab to load that document.
• When there are more tabs than fit the width of the page, the extra tabs collapse into a More menu.

Use this to keep related documentation next to the dashboards it describes, such as a runbook, an onboarding guide, or contribution and ownership details in separate documents.

Navigate to resources from Markdown links

Markdown links are context-aware. A link that points to a provisioned resource file, such as a dashboard JSON file or a folder, opens the matching page inside Grafana when you select it. This lets you move between documentation and dashboards the same way you move between provisioned resources.

When a link doesn’t match a provisioned resource, Grafana opens the file in the host repository, so the same README still works when viewed on GitHub or GitLab.

Render Mermaid diagrams

Grafana renders Mermaid diagrams defined in your Markdown documents. Use them to embed architectural diagrams, incident runbook flows, or data pipeline overviews next to the dashboards that monitor them. Use a fenced code block with the mermaid language to include a diagram:

Markdown Copy

```mermaid
flowchart LR
  A[Ingest] --> B[Store]
  B --> C[Query]
  C --> D[Dashboard]
```

Grafana replaces the code block with the rendered diagram and matches it to your light or dark theme.

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. Use additional documents for runbooks, architectural diagrams, or onboarding guidelines that belong next to the dashboards.

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