From dad19d22bd4a8db049405edbef0825c26ad37b33 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Sat, 15 Nov 2025 09:01:36 +0000 Subject: [PATCH] [release-12.3.1] Docs: Full instance Git Sync notes (#113979) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Roberto Jiménez Sánchez Co-authored-by: Anna Urbiztondo --- .../provision-resources/file-path-setup.md | 15 +++- .../provision-resources/git-sync-setup.md | 73 ++++++++----------- .../provision-resources/intro-git-sync.md | 29 +++++++- 3 files changed, 70 insertions(+), 47 deletions(-) diff --git a/docs/sources/as-code/observability-as-code/provision-resources/file-path-setup.md b/docs/sources/as-code/observability-as-code/provision-resources/file-path-setup.md index fafbe8d9ec3..f2cd24a46b1 100644 --- a/docs/sources/as-code/observability-as-code/provision-resources/file-path-setup.md +++ b/docs/sources/as-code/observability-as-code/provision-resources/file-path-setup.md @@ -43,8 +43,7 @@ To set up file sync with local with local files, you need to: Local file provisioning using **Administration** > **Provisioning** will eventually replace the traditional methods Grafana has used for referencing local file systems for dashboard files. {{< admonition type="note" >}} -For production system, we recommend using the `folderFromFilesStructure` capability instead of **Administration** > **Provisioning** to include dashboards from a local file system in your Grafana instance. -Refer to [Provision Grafana](https://grafana.com/docs/grafana//administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information. +For production systems, use the `folderFromFilesStructure` capability instead of **Administration** > **Provisioning** to include dashboards from a local file system in your Grafana instance. Refer to [Provision Grafana](https://grafana.com/docs/grafana//administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information. {{< /admonition >}} ### Limitations @@ -128,6 +127,18 @@ The set up process verifies the path and provides an error message if a problem ### Choose what to synchronize +#### Synchronization limitations + +Full instance sync is not available in Grafana Cloud. + +In Grafana OSS/Enterprise: + +- If you try to perform a full instance sync with resources that contain alerts or panels, the connection will be blocked. +- You won't be able to create new alerts or library panels after setup is completed. +- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the provisioned repository and connect again with folder sync. + +#### Set up synchronization + Choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections). - Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to. diff --git a/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md b/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md index fb73f897970..0a7bd7be28b 100644 --- a/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md +++ b/docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md @@ -64,6 +64,8 @@ Refer to [Known limitations](https://grafana.com/docs/grafana// {{< /admonition >}} +### Requirements + To set up Git Sync, you need: - Administration rights in your Grafana organization. @@ -131,34 +133,37 @@ To connect your GitHub repository, follow these steps: ### Choose what to synchronize +In this step you can decide which elements to synchronize. Keep in mind the available options depend on the status of your Grafana instance. + +- If the instance contains resources in an incompatible data format, you'll have to migrate all the data using instance sync. Folder sync won't be supported. +- If there is already another connection using folder sync, instance sync won't be offered. + +#### Synchronization limitations + +Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet. + {{< admonition type="caution" >}} -Git Sync only works with specific folders for the moment. Full-instance sync is not currently supported. Refer to [Supported resources](/docs/grafana//observability-as-code/provision-resources/intro-git-sync#supported-resources) for more details about which resources you can sync. +Refer to [Known limitations](https://grafana.com/docs/grafana//observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync. Refer to [Supported resources](/docs/grafana//observability-as-code/provision-resources/intro-git-sync#supported-resources) for details about which resources you can sync. {{< /admonition >}} -In this step you can decide which elements to synchronize. Keep in mind the available options depend on the status of your GitHub repository. The first time you connect Grafana with a GitHub repository, you need to synchronize with external storage. If you are syncing with a new or empty repository, you won't have an option to migrate dashboards. +Full instance sync is not available in Grafana Cloud. -1. Choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections). +In Grafana OSS/Enterprise: + +- If you try to perform a full instance sync with resources that contain alerts or panels, Git Sync will block the connection. +- You won't be able to create new alerts or library panels after the setup is completed. +- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the synced repository and connect again with folder sync. + +#### Set up synchronization + +To set up synchronization, choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections). - Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to. - - Choose **Sync external storage to new Grafana folder** to sync external resources into a new folder without affecting the rest of your instance. You can repeat this process for up to 10 connections. -1. Enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI. -1. Click **Synchronize** to continue. - - +Next, enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI. Click **Synchronize** to continue. ### Choose additional settings @@ -166,7 +171,6 @@ Finally, you can set up how often your configured storage is polled for updates. 1. For **Update instance interval (seconds)**, enter how often you want the instance to pull updates from GitHub. The default value is 60 seconds. 1. Optional: Select **Read only** to ensure resources can't be modified in Grafana. - 1. Optional: If you have the Grafana Image Renderer plugin configured, you can **Enable dashboards previews in pull requests**. If image rendering is not available, then you can't select this option. For more information, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer). 1. Select **Finish** to proceed. @@ -182,23 +186,11 @@ You can extend Git Sync by getting instant updates and pull requests using webho ### Set up webhooks for realtime notification and pull request integration -When connecting to a GitHub repository, Git Sync use webhooks to enable real-time updates from GitHub public repositories or enable the pull request integration. -Without webhooks, the polling interval is set in the final configuration screen (default is 60 seconds). -Your Grafana instance must be exposed to the public internet. -You can do this via port forwarding and DNS, a tool such as `ngrok`, or any other method you prefer. +When connecting to a GitHub repository, Git Sync uses webhooks to enable real-time updates from GitHub public repositories or enable pull request integrations. Without webhooks, the polling interval is set in the final configuration screen, and the default is 60 seconds. If you use local storage, then Git Sync only provides periodic pulling. -The permissions set in your GitHub access token provide the authorization for this communication. +You can set up webhooks with whichever service or tooling you prefer. You can use Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as `ngrok`. -If you use local storage, then Git Sync only provides periodic pulling. - - - -Set up webhooks with whichever service or tooling you prefer. -For example, you can use Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as `ngrok`. +To set up webhooks you need to expose your Grafana instance to the public Internet. You can do this via port forwarding and DNS, a tool such as `ngrok`, or any other method you prefer. The permissions set in your GitHub access token provide the authorization for this communication. After you have the public URL, you can add it to your Grafana configuration file: @@ -207,23 +199,22 @@ After you have the public URL, you can add it to your Grafana configuration file root_url = https://PUBLIC_DOMAIN.HERE ``` -You can check the configured webhooks in the **View** link for your GitHub repository from **Administration** > **Provisioning**. +To check the configured webhooks, go to **Administration** > **Provisioning** and click the **View** link for your GitHub repository. -#### Necessary paths +#### Expose necessary paths only -If your security setup does not permit publicly exposing the Grafana instance, you can either choose to allowlist the GitHub IP addresses, or expose only the necessary paths. +If your security setup does not permit publicly exposing the Grafana instance, you can either choose to `allowlist` the GitHub IP addresses, or expose only the necessary paths. -The necessary paths required to be exposed are (RegExp): +The necessary paths required to be exposed are, in RegExp: - `/apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$` ### Set up image rendering for dashboard previews -By setting up image rendering, you can add visual previews of dashboard updates directly in pull requests. -Image rendering also requires webhooks. +Set up image rendering to add visual previews of dashboard updates directly in pull requests. Image rendering also requires webhooks. -You can enable this capability by installing the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer). +To enable this capability, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer). ## Modify configurations after set up is complete diff --git a/docs/sources/as-code/observability-as-code/provision-resources/intro-git-sync.md b/docs/sources/as-code/observability-as-code/provision-resources/intro-git-sync.md index ac5c1da66cc..4d9bda529a3 100644 --- a/docs/sources/as-code/observability-as-code/provision-resources/intro-git-sync.md +++ b/docs/sources/as-code/observability-as-code/provision-resources/intro-git-sync.md @@ -10,6 +10,12 @@ labels: - enterprise - oss - cloud +refs: + roles-and-permissions: + - pattern: /docs/grafana/ + destination: /docs/grafana//administration/roles-and-permissions/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/account-management/authentication-and-permissions/cloud-roles/ title: Git Sync weight: 100 canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/intro-git-sync/ @@ -66,7 +72,15 @@ With Git Sync, you can make changes to the files in the provisioned folder in Gi ## Known limitations -Git Sync is under development and the following limitations apply: +{{< admonition type="caution" >}} + +Refer to [Requirements](https://grafana.com/docs/grafana//observability-as-code/provision-resources/git-sync-setup#requirements/) to learn what you need to use Git Sync. + +{{< /admonition >}} + +**Git Sync is under development and the following limitations apply.** + +**Synced resources** - You can only sync dashboards and folders. Refer to [Supported resources](#supported-resources) for more information. - If you're using Git Sync in Grafana OSS and Grafana Enterprise, some resources might be in an incompatible data format and won't be synced. @@ -78,8 +92,15 @@ Git Sync is under development and the following limitations apply: **Authentication** - You can only authenticate in GitHub using your Personal Access Token token. + +**Permission management** + +- You cannot modify the permissions of a provisioned folder after you've synced it. +- Default permissions are: Admin = Admin, Editor = Editor, and Viewer = Viewer. Refer to [Roles and permissions](ref:roles-and-permissions) for more information. + +**Compatibility** + - Support for native Git, Git app, and other providers, such as GitLab or Bitbucket, is on the roadmap. -- 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. ## Supported resources @@ -96,9 +117,9 @@ A resource can be: | **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. | -### Instance states +### Git Sync instance states -An instance can be in one of the following states: +An 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.