Add non-provisioned resources from Grafana

{{< admonition type="note" >}}

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

{{< /admonition >}}

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

• Add a dashboard using Import dashboards
• Export an existing dashboard from the Grafana UI as a copy
• Add a dashboard with Grafana CLI
• Copy a dashboard as JSON and commit to the provisioned repository

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:

1. Go to the Dashboards tab of you connection.
2. On the top right corner, click New.
3. Select Import dashboard and you'll be redirected to the wizard.
4. Upload or paste the dashboard JSON.
5. Fill in the relevant fields, including the branch and repository folder, and press Import.
6. 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.

{{< admonition type="note" >}}

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

{{< /admonition >}}

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:

1. Make sure the dashboard is in Editable mode.
2. Select Save or Save as from the top-right corner.
3. 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.
4. Click Save.
5. 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.

{{< admonition type="note" >}}

For more information refer to the gcx documentation.

{{< /admonition >}}

To add a dashboard with gcx, follow these steps:

1. Set up the gcx context to point to your instance as documented in Defining contexts.

2. Pull the resources you want to sync from the instance to your local repository:

   Copy

   gcx resources pull dashboards --path <REPO_PATH>
   

3. Commit and push the resources to your Git repository:

   Copy

   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

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

5. Trigger a new pull to complete the sync. The resources are recreated as provisioned, with their original UIDs, so existing links keep working.

{{< admonition type="note" >}}

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

{{< /admonition >}}

Add a dashboard via JSON export

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

1. Export the dashboard as JSON.
2. Convert it to the Custom Resource Definition (CRD) format required by the Grafana App Platform.
3. Commit the converted file to your Git repository.
4. 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.
5. Trigger a new pull to complete the sync. The resources are recreated as provisioned, with their original UIDs, so existing links keep working.

{{< admonition type="note" >}}

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

{{< /admonition >}}

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.