Documentation Grafana documentation Observability as Code Provision resources and sync dashboards Work with provisioned dashboards

Work with provisioned dashboards

Using Provisioning, you can choose to store your dashboard JSON files in either GitHub repositories using Git Sync or a local file path.

For more information, refer to the Dashboards documentation.

Provisioning methods

Dashboards and folders synchronized using Git Sync or a local file path are referred to as “provisioned” resources.

Of the two experimental options, 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. For more information on configuring Git Sync, refer to Set up Git Sync.

Local path provisioning

Using the local path provisioning makes files from a specified path available within Grafana. These provisioned resources can only be modified in the local files and not within Grafana. Any changes made in the configured local path are updated in Grafana.

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.

Git Sync changes the behavior in Grafana for dashboards that are saved in Git Sync:

• 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.
• Any changes to a provisioned resources have to be saved to the repository by opening a pull request or committing directly to the main branch.

You can set a single folder, or multiple folders to a different repository, with up to 10 connections.

Git workflow with dashboards

By default, Git version control uses a branch-based workflow for changes. This means that you can:

• Commit changes to an existing branch (such as main) or save them to a new branch in your GitHub repository.
• 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.

Add and save a new dashboard

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, the steps are similar to Save dashboard changes to GitHub.

1. Select Save to preserve the new dashboard.
2. Enter a title for the dashboard and a description.
3. Select the provisioned folder from the Folder drop-down list.
4. In Path, provide the path for your repository, ending in a JSON or YAML file.
5. 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.
6. Select Save.

Save dashboard changes to GitHub

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

1. Select Edit to update a provisioned dashboard. Make your desired changes.

2. Click Save dashboard.

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

4. Optional: Select the Changes tab to view the differences between the updates you made and the original resource.

5. Select Save.

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

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

Grafana updates when the changes from the GitHub repository sync.

Tips

• Use GitHub pull requests for changes to maintain review processes.
• Provide clear commit messages describing your changes.
• Regularly sync your repository to keep Grafana up to date.
• Review the Events tab to monitor sync status.

Manage dashboards provisioned with file provisioning

To update any resources in the local path, you need to edit the files directly and then save them locally. These changes are synchronized to Grafana. However, you can’t create, edit, or delete these resources using the Grafana UI.

For more information, refer to How it works.

Refer to Set up file provisioning for configuration instructions.