Deploy, configure and provision Grafana with as code workflows on Grafana Labs

Introduction to Git Sync

Wed, 28 Oct 2026 09:22:36 +0000

Introduction to Git Sync

Git Sync in Grafana lets you synchronize your resources so you can store your dashboards as JSON files in any Git provider and manage them as code. You and your team can version control, collaborate, and automate deployments efficiently.

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

How it works

Git Sync allows you to connect external resources with your Grafana instance. After setup, all synchronized resources live in Git under the provisioned folder, and you can continue to have non-provisioned resources outside that folder.

Git Sync is bidirectional, so you can modify provisioned resources both from the Grafana UI or from the synced repository, and changes will be reflected in both places.

Git Sync is available for any Git provider through a Pure Git repository type, and has specific enhanced integrations for GitHub, GitHub Enterprise, GitLab and Bitbucket. Refer to Usage and performance limitations for further details, including usage tiers.

Refer to key concepts for more information on how Git Sync works.

Make changes in the Grafana UI

Whenever you modify a dashboard directly from the UI, you can also commit those changes to your synchronized Git repositories upon saving. You can configure settings to either enforce PR approvals before merging in your repository, or allow direct commits.

Make changes in your Git repositories

Your Grafana instance polls the provisioned Git resources to synchronize. If you made any changes in your synchronized Git repositories, they will be updated in the Grafana database as well. The Grafana UI reads from the database and updates the UI to reflect these changes.

Without webhooks, Grafana polls for changes at the specified interval. The default polling interval is 60 seconds, and you can change this setting in the Grafana UI.
If you enable the webhooks feature, repository notifications appear almost immediately.

Common use cases

Note
Refer to Git Sync deployment scenarios for sample scenarios, including architecture and configuration details.

You can use Git Sync for the following use cases:

Version control and auditing

Organizations can maintain a structured, version-controlled history of Grafana dashboards. The version control lets you revert to previous versions when necessary, compare modifications across commits, and ensure transparency in dashboard management.

Additionally, having a detailed history of changes enhances compliance efforts, as teams can generate audit logs that document who made changes, when they were made, and why.

Automated deployment and CI/CD integration

Teams can streamline their workflow by integrating dashboard updates into their CI/CD pipelines. By pushing changes to GitHub, automated processes can trigger validation checks, test dashboard configurations, and deploy updates programmatically using the gcx CLI and Foundation SDK.

This reduces the risk of human errors, ensures consistency across environments, and enables a faster, more reliable release cycle for dashboards used in production monitoring and analytics.

Collaborative dashboard development

With Git Sync, multiple users can work on dashboards simultaneously without overwriting each other’s modifications. By leveraging pull requests and branch-based workflows, teams can submit changes for review before merging them into the main branch. This process not only improves quality control but also ensures that dashboards adhere to best practices and organizational standards.

Additionally, GitHub’s built-in discussion and review tools facilitate effective collaboration, making it easier to address feedback before changes go live.

Multi-environment synchronization

Enterprises managing multiple Grafana instances, such as development, staging, and production environments, can seamlessly sync dashboards across these instances. This ensures consistency in visualization and monitoring configurations, reducing discrepancies that might arise from manually managing dashboards in different environments.

By using Git Sync, teams can automate deployments across environments, eliminating repetitive setup tasks and maintaining a standardized monitoring infrastructure across the organization.

Disaster recovery and backup

By continuously syncing dashboards to GitHub, organizations can create an always-updated backup, ensuring dashboards are never lost due to accidental deletion or system failures.

If an issue arises, such as a corrupted dashboard, unintended modification, or a system crash, teams can quickly restore the latest functional version from the Git repository. This not only minimizes downtime but also adds a layer of resilience to Grafana monitoring setups, ensuring critical dashboards remain available when needed.

Build dashboards as code

Because dashboards are defined in JSON files, you can enable as-code workflows where the JSON file is an output from Go, TypeScript, or another coding language in the format of a dashboard schema.

To learn more about creating dashboards in a coding language to provision them for Git Sync, refer to the Foundation SDK documentation.

Explore Git Sync

Refer to the following documents to learn about Git Sync in depth:

Git Sync Key concepts
Key concepts to understand how Git Sync works.
Usage and performance limitations
Git Sync usage tiers, compatible Git providers, and known limitations.
Set up Git Sync
Instructions for setting up Git Sync, so you can provision GitHub repositories for use with Grafana.
- Setup prerequisites
  Prerequisites for Git Sync, so you can provision GitHub repositories for use with Grafana.
- Set up Git Sync as code
  Instructions for setting up Git Sync as code, so you can provision Git repositories for use with Grafana.
- Set up Git Sync with Terraform
  Instructions for setting up Git Sync as code, so you can provision Git repositories for use with Grafana.
- Instantaneous pulling and dashboard previews
  Instructions for extending Git Sync for real-time notification and image rendering.
Add non-provisioned resources from Grafana
Export non-provisioned resources from Grafana.
- Cherry-pick and copy individual dashboards
  Cherry-pick and copy individual dashboards.
- Migrate existing dashboards to Git Sync
  Migrate existing dashboards to Git Sync.
Work with provisioned repositories in Git Sync
Instructions for working with Git Sync to perform common tasks, such as saving dashboards to GitHub and synchronizing changes with Grafana.
Work with provisioned dashboards in Git Sync
Update, save, and modify provisioned resources in Grafana using Git Sync.
Git Sync permissions and access control
Learn about permissions and access control for Git Sync, including required Grafana roles and repository permissions.
Configure Git repository protection
Learn how to protect your Git repository and control who can read or write dashboard source code when using Git Sync.
Git Sync deployment scenarios
Learn about common Git Sync deployment patterns and configurations for different organizational needs
- Single instance Git Sync
  Synchronize a single Grafana instance with a Git repository
- Git Sync for development and production environments
  Use separate Grafana instances for development and production with Git-controlled promotion
- Git Sync with regional replication
  Synchronize multiple regional Grafana instances from a shared Git location
- Testing sandboxes Git Sync
  Use a shared sandbox branch for short-lived projects and experimentation before promoting changes to the main branch
- Git Sync for high availability environments
  Run multiple Grafana instances serving traffic simultaneously, synchronized via Git Sync
- Multiple team Git Sync
  Use multiple Git repositories with one Grafana instance, one repository per team

Provision resources on-prem

Wed, 28 Oct 2026 09:22:36 +0000

On-prem file provisioning

Note
On-prem file provisioning is available in Grafana v12 and later for open source and Enterprise editions. It’s not available in Grafana Cloud. This new file provisioning feature is only available for dashboards and doesn’t replace classic provisioning for the time being.

For classic provisioning using configuration files refer to Provision Grafana.

On-prem local file provisioning allows you to add resources that are stored in your local file system to your Grafana instance. You can configure how to save your dashboards’ JSON and other files from your local file system into a single or multiple folders in a different repository, with up to 10 connections.

You can set it up using the UI or as code with the Grafana CLI. Refer to Set up file provisioning for details.

File provisioning uses the same Repository resource as Git Sync, with the repository type set to local.

How it works

On-prem file provisioning is only available for dashboards at the moment.

After setting up file provisioning:

The dashboards saved in your GitHub repository or local folder appear in Grafana in the provisioned folder.
The dashboards and folders saved to the local path are referred to as provisioned resources and are labeled as such in the Grafana UI.

You can only modify provisioned dashboards locally.

Any changes made in the provisioned files are reflected in the Grafana database. The Grafana UI reads the database and updates the UI to reflect these changes.
You can’t use the Grafana UI to edit or delete provisioned resources.

Grafana Terraform provider

Wed, 28 Oct 2026 09:22:36 +0000

Grafana Terraform provider

The Grafana Terraform provider provisions configuration management resources for Grafana. Grafana administrators can manage dashboards, data sources, plugins, alerts and collectors, add synthetic monitoring probes and checks, manage identity and access, and more, using the Terraform provider.

To manage the entire Grafana ecosystem of resources on either Grafana Cloud or OSS deployments of Grafana, it’s best to use the Terraform Grafana provider because it supports the most Grafana resources compared to Grafana’s other as-code solutions.

The following guides help you get started using Terraform to manage your Grafana Cloud stack:

Create and manage a Grafana Cloud stack using Terraform: Learn how to create a Grafana Cloud stack and add a data source and dashboard using Terraform.
Create and manage dashboards using Terraform and GitHub Actions: Learn how to create and manage multiple dashboards represented as JSON source code for Grafana using Terraform and GitHub Actions.
Managing IRM on Grafana Cloud using Terraform: Learn how to connect an integration to Grafana IRM, configure escalation policies, and add your on-call schedule using Terraform.
Managing Fleet Management in Grafana Cloud using Terraform: Learn how to create collectors and pipelines in Grafana Fleet Management using Terraform. For Grafana Fleet Management users, the Grafana Terraform provider is best used to preregister new collectors before they are operational or add remote attributes to collectors already registered with the service.
Managing Frontend Observability in Grafana Cloud using Terraform: Learn how to manage resources in Frontend Observability using Terraform.
Manage Cloud Provider Observability in Grafana Cloud using Terraform: Learn how to manage Amazon CloudWatch and Microsoft Azure resources in Cloud Provider Observability using Terraform.
Manage Knowledge Graph in Grafana Cloud using Terraform: Learn how to create and manage notification alerts, suppressed assertions, custom model rules, log, trace, and profile configurations, threshold configurations, and Prometheus rules in Grafana Cloud Knowledge Graph using Terraform.
Install plugins in Grafana Cloud using Terraform: Learn how to install plugins in Grafana Cloud using Terraform.
Manage saved queries using Terraform: Learn how to create and import saved queries, also known as the query library, using Terraform.
Manage secrets in Grafana Cloud using Terraform: Learn how to create, rotate, and manage secure values in Grafana Secrets Management using Terraform.

Grafana Ansible collection

Wed, 28 Oct 2026 09:22:36 +0000

Grafana Ansible collection

The Grafana Ansible collection provides configuration management resources for Grafana Cloud. You can use it to manage:

Grafana Cloud stacks
Dashboards
Data sources
Folders
Alerting contact points
Notification policies
API keys

If your resources aren’t currently available in the Grafana Ansible collection, you can manage them on Grafana Cloud programmatically by writing Ansible playbooks that use the Ansible built-in URI module to call the HTTP APIs to manage resources for the Grafana Cloud portal, as well as those within a stack.

Learn more

Refer to Create and manage a Grafana Cloud stack using Ansible to learn how to create a Grafana Cloud stack and add a data source and dashboard using Ansible.

To learn more about managing Grafana with Infrastructure as code:

Grafana Agent (deprecated)

Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

The Ansible collection also houses Grafana Agent role, which is now deprecated.

Grafana Operator

Wed, 28 Oct 2026 09:22:36 +0000

Grafana Operator

The Grafana Operator is a Kubernetes operator built to help you manage your Grafana instances and its resources in a Kubernetes environment. The Grafana Operator automatically syncs Kubernetes custom resources and actual resources in your Grafana instance, and allows you to install and manage local Grafana instances, dashboards and data sources in Kubernetes or OpenShift.

While the Grafana Operator simplifies many aspects of operating Grafana and its resources on Kubernetes, its current support is mainly focused on managing dashboards, folders, and data sources. Advanced features like alerting and plugins (only works for OSS) are not supported yet.

Install the Grafana Operator

To install the Grafana Operator in your Kubernetes cluster, run the following command in your terminal:

helm repo add grafana https://grafana.github.io/helm-charts
helm upgrade -i grafana-operator grafana/grafana-operator

For other installation methods, refer to the Grafana Operator Installation documentation.

Use the Grafana Operator

Use the following guides to use the Grafana Operator to manage your Grafana instance:

Manage data sources, and dashboards with folders using the Grafana Operator describes how to add a folders, data sources, and dashboards using the Grafana Operator.
Manage Dashboards with GitOps Using ArgoCD describes how to create and manage dashboards using ArgoCD and Grafana Operator.

Use the Grafana Crossplane provider

Note
The Grafana Crossplane provider is intended for existing Crossplane users looking to manage Grafana resources from within Kubernetes and as Kubernetes manifests for the GitOps pipelines. To use the Crossplane provider, you must have the Crossplane CLI and Crossplane installed in the Kubernetes cluster. Note that the Crossplane provider is in an alpha stage, so it has not reached a stable state yet.

The Grafana Crossplane provider is built using Terrajet and provides support for all resources supported by the Grafana Terraform provider. It enables you to define Grafana resources as Kubernetes manifests and it also help users who build their GitOps pipelines around Kubernetes manifests using tools like ArgoCD.

To get started with the Grafana Crossplane provider, install Crossplane in the Kubernetes cluster and use this command to install the provider:

kubectl crossplane install provider grafana/crossplane-provider-grafana:v0.1.0

During installation of the provider, CRDs for all the resources supported by the Terraform provider are added to the cluster so users can begin defining their Grafana resources as Kubernetes custom resources. The Crossplane provider ensures that whatever is defined in the custom resource definitions is what is visible in Grafana UI. If you make any changes directly in the UI, the changes will be discarded when the provider syncs again. This helps ensure that whatever is defined via code in the cluster will be the source of truth for Grafana resources.

For more information, refer to the examples folder in the Grafana Crossplane repository.

Foundation SDK

Wed, 28 Oct 2026 09:22:36 +0000

Get started with the Grafana Foundation SDK

The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using strongly typed code. By writing your dashboards as code, you can:

Leverage strong typing: Catch errors at compile time, ensuring more reliable configurations.
Enhance version control: Track changes seamlessly using standard version control systems like Git.
Automate deployments: Integrate dashboard provisioning into your CI/CD pipelines for consistent and repeatable setups.

The SDK supports multiple programming languages, including Go, TypeScript, Python, PHP, and Java, so you can choose the one that best fits your development environment. Refer to the Grafana Foundation SDK GitHub repository for further details.

Grafana Foundation SDK overview

Here’s a quick overview of how the Grafana Foundation SDK works:

Composable builder pattern: You can chain different builder blocks to define dashboards fluently. You start with a DashboardBuilder, then add panels, queries, and other components step by step.
Safe strong typing: Everything in the SDK is strongly typed. This gives you autocompletion in your IDE, catches mistakes early, and helps ensure you’re always using valid configuration values.
Configuration with structured options: When a configuration get complex (like data reduction or display settings), the SDK uses typed option builders to keep things readable, predictable, and easy to control.

As you build more advanced dashboards, you’ll work with additional builders and types to support richer functionality. The SDK supports not just panels and queries, but also variables, thresholds, field overrides, transformations, and more. Refer to the full API reference to explore what’s possible.

Refer to Foundation SDK key concepts for a more extensive explanation, and read on to see these concepts in action.

Before you begin

Ensure you have the following prerequisites:

Programming environment: Set up for your chosen language. For example: Go, Node.js for TypeScript, or Python 3.x for Python.
Grafana instance: A running Grafana instance compatible with the SDK (Grafana v10.0 or higher).
Package manager: Appropriate for your language, for example, npm or yarn for TypeScript or pip for Python.

Install the Grafana Foundation SDK

To install the Foundation SDK:

Clone the intro-to-foundation-sdk repository to access examples and a docker-compose stack.
Select the go or typescript tab to view instructions to install the SDK. For other languages, refer to the Grafana Foundation SDK documentation for installation instructions.

typescript

go get github.com/grafana/grafana-foundation-sdk/go@latest

npm install @grafana/grafana-foundation-sdk

Create a dashboard

See the following examples in Go and Typescript to create a simple dashboard:

This code defines a dashboard titled “My Dashboard” with a two panels:

a simple stat panel displaying a version number, and
a time series panel displaying randomized data from the testdata data source random_walk scenario.

typescript

package main

// Import the appropriate Grafana Foundation SDK packages
import (
  "encoding/json"
  "log"

  "github.com/grafana/grafana-foundation-sdk/go/cog"
  "github.com/grafana/grafana-foundation-sdk/go/common"
  "github.com/grafana/grafana-foundation-sdk/go/dashboard"
  "github.com/grafana/grafana-foundation-sdk/go/stat"
  "github.com/grafana/grafana-foundation-sdk/go/testdata"
  "github.com/grafana/grafana-foundation-sdk/go/timeseries"
)

func main() {
  // Define a data source reference for our testdata data source
  testdataRef := dashboard.DataSourceRef{
    Type: cog.ToPtr("grafana-testdata-datasource"),
    Uid:  cog.ToPtr("testdata"),
  }

  // Define our dashboard as strongly typed code
  builder := dashboard.NewDashboardBuilder("My Dashboard").
    WithPanel(
      stat.NewPanelBuilder().
        Title("Version").
        Datasource(testdataRef).
        ReduceOptions(common.NewReduceDataOptionsBuilder().
          Calcs([]string{"lastNotNull"}).
          Fields("/.*/")).
        WithTarget(
          testdata.NewDataqueryBuilder().
            ScenarioId("csv_content").
            CsvContent("version\nv1.2.3"),
        ),
    ).
    WithPanel(
      timeseries.NewPanelBuilder().
        Title("Random Time Series").
        Datasource(testdataRef).
        WithTarget(
          testdata.NewDataqueryBuilder().
            ScenarioId("random_walk"),
        ),
    )

  // Build the dashboard - errors in configuration will be thrown here
  dashboard, err := builder.Build()
  if err != nil {
    log.Fatalf("failed to build dashboard: %v", err)
  }

  // Output the generated dashboard as JSON
  dashboardJson, err := json.MarshalIndent(dashboard, "", "  ")
  if err != nil {
    log.Fatalf("failed to marshal dashboard: %v", err)
  }

  log.Printf("Dashboard JSON:\n%s", dashboardJson)
}

// Import the appropriate Grafana Foundation SDK packages
import * as common from '@grafana/grafana-foundation-sdk/common';
import * as dashboard from '@grafana/grafana-foundation-sdk/dashboard';
import * as stat from '@grafana/grafana-foundation-sdk/stat';
import * as testdata from '@grafana/grafana-foundation-sdk/testdata';
import * as timeseries from '@grafana/grafana-foundation-sdk/timeseries';

// Define a data source reference for our testdata data source
const testDataRef: dashboard.DataSourceRef = {
  type: 'grafana-testdata-datasource',
  uid: 'testdata',
};

// Define our dashboard as strongly typed code
const builder = new dashboard.DashboardBuilder('My Dashboard')
  .withPanel(
    new stat.PanelBuilder()
      .title('Version')
      .reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'))
      .datasource(testdataRef)
      .withTarget(new testdata.DataqueryBuilder().scenarioId('csv_content').csvContent('version\nv1.2.3'))
  )
  .withPanel(
    new timeseries.PanelBuilder()
      .title('Random Time Series')
      .datasource(testdataRef)
      .withTarget(new testdata.DataqueryBuilder().scenarioId('random_walk'))
  );

// Build the dashboard - errors in configuration will be thrown here
const dashboard = builder.build();

// Output the generated dashboard as JSON
console.log(JSON.stringify(dashboard, null, 2));

Export and use the JSON

After you’ve defined your dashboard as code, build the final dashboard representation using the dashboard builder, typically using the build() function depending on language choice, and output the result as a JSON.

With the JSON payload, you can:

Manually import: Paste into Grafana’s dashboard import feature.
Automate: Use the Grafana API, the Grafana CLI, or Git Sync to programmatically upload the dashboard JSON.

Explore a real-world example

If you want to explore further and see a more real-world example of using the Grafana Foundation SDK, watch the following walkthrough:

In this video, we generate a dashboard from code and deploy it using the Grafana API, covering patterns and practices you’d use in production environments. It also includes a working example of a web service that emits metrics and logs, and shows how to deploy a dashboard alongside it using Docker Compose.

You can find the full source code for this example in the intro-to-foundation-sdk repository.

Next steps

Now that you understand the basics of using the Grafana Foundation SDK, here are some next steps:

Explore more features: Check out the full API reference to learn about advanced dashboard configurations.
Version control your dashboards: Store your dashboard code in a Git repository to track changes over time.
Automate dashboard provisioning with CI/CD: Integrate the SDK into your CI/CD pipeline to deploy dashboards automatically.
Learn about Grafana Git Sync, which lets you synchronize your resources so you can store your dashboards as JSON files stored in GitHub and manage them as code.