Documentation Grafana Cloud Learn and build As code Observability as code Git Sync Add non-provisioned resources Migrate existing dashboards

Migrate existing dashboards to Git Sync

If you migrate your existing non-provisioned dashboards under Git Sync, dashboards keep their UIDs, so existing links, references, and bookmarks keep working. Because the UID is preserved, Git Sync adopts the resource in place, and you must delete the original resource so Git Sync can take over its UID.

The migration follows these steps:

1. Before you begin: Back up your instance and understand what Git Sync manages.
2. Step 1: Export the resources to your repository: Export with UIDs preserved and commit.
3. Step 2: Delete the original dashboards: Required so Git Sync can adopt each dashboard by UID.
4. Step 3: Validate the migration: Confirm the resources are synced before moving on.

Before you begin

Because migrating involves deleting resources, read this section and plan carefully before you start.

To migrate safely, keep in mind the following:

• Back up your instance first. Export or snapshot your dashboards, folders, alert rules, and library panels before you delete anything. Deleted resources can’t be restored from the Grafana UI.
• Migrate folder by folder. Start with a single folder, complete the full migration for it, and validate the result before moving to the next one. This limits the impact if something goes wrong and lets you get comfortable with the process.
• Do not delete a folder that contains alerts or library panels. Git Sync only manages dashboards and folders. Alerts, data sources, library panels, and other resources are not supported yet, and Git Sync will not recreate them. Deleting the folder deletes them permanently.

Manage and delete migrated resources

With a folder or folderless sync, Git Sync recreates dashboards and folders:

• You’ll have to delete each original dashboard you’re migrating so Git Sync can take over its UID.
• You don’t need to delete your original folders to migrate the dashboards inside them. Git Sync creates its own new folders when it syncs with your existing repository, deriving each folder’s UID from the folder’s path in the repository. These folders are independent from your existing ones, even if they share the same name.
• However, Git Sync doesn’t recreate alerts or library panels. Deleting or recreating a folder to match your repository structure permanently deletes any alert rules and library panels it holds, and they are not restored.

Refer to Step 2: Delete the original dashboards for more details.

Keep your original resources and set them apart

After a migration you’ll have your original folder (holding any alerts and library panels) alongside the new Git Sync folder of the same name. To avoid confusion, rename your original folders or move them under a single top-level Alerts & Library Panels folder. This keeps the unsupported resources intact and clearly separated from the provisioned dashboards.

If you need links to your original folders to keep working, refer to Preserve links to the original folders.

Step 1: Export the resources to your repository

Export the dashboards you want to migrate so that each file keeps the dashboard’s original UID (metadata.name), then commit the files to your Git repository. You can use either of the following:

• Export with the Grafana CLI
• Export as a JSON resource file

Export with the Grafana CLI

You can export existing dashboards from the terminal or from agentic coding tools using the gcx CLI. 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.

To export dashboards 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

After you commit the resources, continue to Step 2.

Export as a JSON resource file

To export a dashboard as a JSON resource file, 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.

After you commit the file, continue to Step 2.

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

YAML Copy

{
  '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 name, which must match the original dashboard UID so Git Sync can adopt it. You can find the identifier in the dashboard’s URL or in the exported JSON.
• spec: Wraps your original dashboard JSON.

Step 2: Delete the original dashboards

Delete each original dashboard you’re migrating so Git Sync can take over its UID. Since the exported files keep the original UID, Git Sync can’t provision any dashboard if an unmanaged dashboard with the same UID (metadata.name) still exists in Grafana.

When you delete a dashboard, 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.

Manage migrated folders

You don’t need to delete your migrated folders, as Git Sync creates its own folders with new, path-derived UIDs. Don’t delete or recreate folders that contain alert rules or library panels, since those resources are deleted permanently and Git Sync does not recreate them. See Before you begin for how to keep and set apart your original folders.

Step 3: Validate the migration

1. Trigger a new pull to complete the sync. The dashboards are recreated as provisioned, with their original UIDs, so existing links keep working.
2. Confirm each dashboard appears in the provisioned folder and opens correctly. It may take a few minutes for changes to appear; if they don’t, refresh the UI manually.
3. Confirm that the alert rules and library panels in your original folders are still present and working.

After you’ve validated one folder, repeat the process for the next one until the migration is complete.

Preserve links to the original folders

By default, Git Sync gives each synced folder a new UID derived from its path in the repository. This means links and URLs that point to your original folders keep pointing to the original folders, not the new provisioned ones.

If you need existing folder links and URLs to resolve to the provisioned folders instead, you can pin a folder’s UID with a folder metadata file so Git Sync reuses the original folder’s UID.

Save unsupported resources

Because this option reuses the original folder’s UID, the synced folder collides with your existing unmanaged folder, and Git Sync can’t take over a UID that still belongs to an unmanaged folder, with the sync failing with a conflict.

To avoid losing unsupported resources, complete these steps for each folder before you sync:

1. Create a new folder and move all alert rules, library panels, and other unsupported resources out of the original folder into it.

• Move alert rules and library panels out of the folder before you delete the folder, since Git Sync does not recreate alerts or library panels.

1. Delete the original folder. Its dashboards should already be exported to the repository from Step 1.
2. Reapply any custom permissions on the new provisioned folder, as folder permissions don’t carry over. Refer to Git Sync permissions and access control.

Reuse the original folder’s UID

To reuse an original folder’s UID, add a _folder.json file to that folder’s directory in the repository:

JSON Copy

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

Where <ORIGINAL_FOLDER_UID> is the UID of your existing folder. You can find it in the folder’s URL.